Implementing Questionnaire Import And Workflow Generation

Tip

Click here to download the JSON (JavaScript Object Notation) snippets included in these topics, and customize them to use according to your requirements.

The Questionnaire Import SPI is a subset of the remote connector SPIs that a connector can implement to support business features of BMC Digital Workplace Catalog beside the initial handshakes (descriptors, health checks) and actions (because each action is, in a way, specific to its connector).

Questionnaire Import

When importing catalog services, it is possible for BMC Digital Workplace Catalog to generate an ad hoc workflow for that service and to import the associated questionnaire in a simple configuration:

The service fulfillment can be triggered by one action of the same connector.
It is be possible to map question or predefined variables to the required inputs of the fulfillment action.

If the connector also implements the Activity SPI for the fulfillment, BMC Digital Workplace Catalog will be able to track its progress and adjust the service request status accordingly.

Note that there is no specific connector capability for this feature: it is an advanced usage of the "catalog provider" one. If a service exposes a fulfillment object with enough information, a wrapper workflow will be generated. If this fulfillment description also references a questionnaire, the questionnaire will also be imported and attached to the workflow.

POST ${connector_path}/com.bmc.dsm.catalog:getService

This specification describes the fulfillment extension to the "com.bmc.dsm.catalog:getService" call already described in the basic catalog SPI.

request

{
  "connectionInstanceId": "DEV",
  "request": {    
    "serviceId": "catalog_item_123"
  }
}

response

Fulfillment via an action:

{
  "response": {
    "services": [
            {
                "id": "1",

				...

				"fulfillment": {
					// Fulfillment type
					// possible values:
					//   CONNECTOR_ACTION: indicates a fulfillment via an action
					//	 EXTERNAL_URL: indicates a link out service
                    "type": "CONNECTOR_ACTION",
					// Unscoped name of the action
                    "action": "submitOrder",
					// (optional) reference to a questionnaire to import
                    "questionnaireId": "questionnaire_789",
					// Description of the inputs of the action in the perspective of generating a workflow.
					// This descriptor duplicates some of the information provided in the general action descriptor.
                    "inputs": [
                      {
						// ID of the action input. Different from name if you need to correlate it with a question ID. 
                        "id": "item_id",
                        "name": "Item ID",
                        "required": true,
						// Indicates whether this input needs to be federated in another "DYNAMIC_INPUTS" inut.
                        "dynamic": false,
						// Possible values:
						//   Text: same as "String" in the action descriptor
						//   Integer
						//   Boolean
						//   DateTime
                        "inputType": "Text",
						// Indicates what part of the request workflow context should be assigned to this input.
						// Possible values:
						//   SERVICE_ID: ID of the corresponding imported service
						//   REQUESTED_BY_LOGIN_NAME
						//   REQUESTED_FOR_LOGIN_NAME
						//   PROCESS_CORRELATION_ID: can be used to resume workflow if it pauses on a "Receive Task" activity.
						//   DYNAMIC_INPUTS: one of the action inputs can receive all the consolidated inputs, which are marked as being "dynamic".
						//   CONNECTION_INSTANCE: ID of the connection instance
						//   ORDER_ID
						//   ORDER_GUID
						//   ORDER_DESCRIPTION
						//   QUANTITY
						//   ONE_TIME_COST: one-time cost of the requested service
						//  				Note that, at runtime, the cost will be passed to the action as "${currency_code} ${amount}" e.g. "USD 123.56",
						//					where the code is 3-letter ISO 4217 currency code.
						//   MONTHLY_COST periodical cost of the requested service recalculated to a monthly basis.
						//  				Note that, at runtime, the cost will be passed to the action as "${currency_code} ${amount}" e.g. "USD 123.56",
						//					where the code is 3-letter ISO 4217 currency code.
                        "inputAssignment": "SERVICE_ID"
                      },
                      {
                        "id": "recipient",
                        "name": "Recipient",
                        "required": true,
                        "dynamic": false,
                        "inputType": "Text",
                        "inputAssignment": "REQUESTED_FOR_LOGIN_NAME",
                        "datasetId": null
                      },
                      {
                        "id": "questions_and_answers",
                        "name": "Answers",
                        "required": false,
                        "dynamic": false,
                        "inputType": "Object",
                        "inputAssignment": "DYNAMIC_INPUTS",
                        "datasetId": null
                      },
					  // The 2 following inputs will be gathered and passed as an "Input Set" data structure to the input marked as "DYNAMIC_INPUTS".
                      {
                        "id": "field1",
                        "name": "Field 1",
                        "required": false,
                        "dynamic": true,
                        "inputType": "Text"
                      },
                      {
                        "id": "field2",
                        "name": "Field 2",
                        "required": false,
                        "dynamic": true,
                        "inputType": "Text"
                      }
                    ]
                }
            }
        ]
  }
}

Fulfillment via an external link:

{
  "response": {
    "services": [
            {
                "id": "1",

				...

				"fulfillment": {
                    "questionnaireId": "questionnaire_789",
                    "externalUrl": "http://example.com/path/to/index.html",
                    "type": "EXTERNAL_URL",
                    "embeddable": true
                }
            }
        ]
  }
}

POST ${connector_path}/com.bmc.dsm.catalog:findQuestionnaire

Returns the description of a questionnaire. This is normally referenced from the service fulfillment description.

request

{
  "connectionInstanceId": "DEV",
  "request": {    
    "questionnaireId": "questionnaire_789"
  }
}

response

{
  "response": {
	// List of the localizations of the specified questionnaire
    "questionnaires": [
            {
				// All localizations should share the same identifier
				"id": "questionnaire_789",
				// null for the default localization, supported ISO code for other localizations
				"locale": null,
				// Elements of the questionnaire in the order of display.
				"questionnaireElements": [
                    {
					  // Formatting of this questionnaire element
					  // Possible values:
					  //   TextField
					  //   TextArea
					  //   DateField
					  //   TimeField
					  //   DatetimeField
					  //   YesNo
					  //   Dropdown
                      //   MultiSelectDropdown
					  //   RadioButtons
					  //   Checkboxes
					  //   Description
					  //   Section
					  //   Attachments
                      "format": "TextArea",
					  // ID of this element in this questionnaire.
                      "id": "element_1",
					  // Plain text label of the questionnaire element
                      "name": "Description of the event",
					  // Rich text description of the questionnaire element
                      "description": null,
                      "required": true,
                      "hidden": false,
                      "readOnly": false,
                      "maxChars": 255,
                      "regex": null,
					  // (optional) ID of the fulfillment input corresponding mapped to this question.
                      "fulfillmentInputId": "field1",
					  // (optional) ID of the dataset used to populate the choices of this question.
                      "datasetId": null,
                      // (optional) Qualification expression used to filter the specified queryable dataset.
                      //     See "Principles of the Remote Connector Service Provider Interface" for the structure of qualifications.
                      "qualificationExpression": null,
					  // (optional) List of the statically defined choices of this multi-choice question.
                      "possibleValues": null,
					  // (optional) List of the default values. Multiple values only apply for multi-select questions likes checkboxes.
                      "defaultValues": null
                    },
                    {
                      "format": "Dropdown",
                      "id": "element_2",
                      "name": "Is it a customer-facing event?",
                      "description": null,
                      "required": true,
                      "hidden": false,
                      "readOnly": false,
                      "maxChars": null,
                      "regex": null,
                      "fulfillmentInputId": null,
                      "datasetId": null,
                      "possibleValues": [
                        {
                          "id": "0",
                          "name": "No"
                        },
                        {
                          "id": "1",
                          "name": "Yes"
                        },
                        {
                          "id": "2",
                          "name": "N/A"
                        }
                      ],
                      "defaultValues": ["0"]
                    },
                    {
                      "format": "TextField",
                      "id": "element_3",
                      "name": "Name of the customer",
                      "description": null,
                      "required": true,
                      "hidden": false,
                      "readOnly": false,
                      "maxChars": null,
                      "regex": null,
                      "fulfillmentInputId": "field2",
                      "datasetId": null,
                      "possibleValues": null,
                      "defaultValues": null
                    },
                    {
                      "format": "RadioButtons",
                      "id": "element_4",
                      "name": "Venue",
                      "description": null,
                      "required": false,
                      "hidden": false,
                      "readOnly": false,
                      "maxChars": null,
                      "regex": null,
                      "fulfillmentInputId": "field3",
                      "datasetId": "VenueDatasetID",
                      "possibleValues": null,
                      "defaultValues": null
                    }
                ],
				// (optional) List of the conditions that apply between elements of the questionnaire.
				"questionnaireConditions": [
					{
						// Id of the multi-choice question, which drives the condition.
						"testedQuestionId": "element_2",
						// IDs of the questionnaire elements, whose visibility is controlled by this condition.
						"controlledElementIds": ["element_3"],
						// IDs of the exact choices (no more, no fewer) that need to be selected for this condition to be fulfilled.
						"expectedAnswerIds": ["1"]
					}
				]
            }
        ]
  }
}

Implementing Questionnaire Import And Workflow Generation

Questionnaire Import

Comments