Skip to main content

Data provisioning

The data provisioning (connector) supports the following scenarios, depending on the target system:

  • creating a ticket for each provisioning task and a separate ticket for each provisioning job (with an option to create a link between them)
  • creating a ticket for each provisioning task
  • creating one ticket for the whole provisioning job, including tasks information

It also supports two variants of reading the ticket status:

  • sending a request to read the status for each ticket independently
  • sending just one request to read the status, even if several tickets were created (this may be useful if there is a parent ticket that represents the overall status or an array with statuses for each child/subtask).

The connector also uses the OPS connector data object type: Support job requests (system name: SYSONB_JOBREQUESTSUPPORT). It is used to indicate parent ticket/issue creation during the provisioning job.

Connector settings​

See the REST Provisioning configuration section for details how to configure the connector.

This connectivity package introduces the following new options:

  • Send all tasks in one request
    Whether all provisioning tasks should be merged and sent in a single HTTP request. An array of multi-value properties are added as separate values to the array, single-value properties are concatenated using the provided separator.

  • Joined property values separator
    Separator of the single-value properties. Shown only if the Send all tasks in one request setting is set to true.

  • Send one request to get all tasks statuses
    Whether the connector should send one HTTP request to get statuses for all provisioning tasks. Select this option if the target system provides an overall status of the whole ticket only, or provides an array with statuses for each provisioning task. The status will be read from the response (using the request item status field value or StateFieldOrPath object detail, if provided).

  • Request item status field
    The field or JSON path storing status. May contain task property values or result values in curly brackets.

  • Request completed values
    Comma separated list of statuses (meaning that the task is completed).

  • Request item pending values
    Comma separated list of statuses (meaning that the task is still pending).

  • Request item failed values
    Comma separated list of statuses (meaning that the task failed or is rejected).

Data model​

See the Code example of the data model in the REST connector section for reference. The REST Relay connector introduces the following new object details:

  • ResourcePathGetStatus
    Relative to the path to get the object status. It may contain property values in curly brackets (like for other resource paths, and additionally result values from the provisioning task).

  • StateFieldOrPath
    The option with the same function as quotation marks "" in relay settings. You can override the value for the specific job. Use this option to overwrite the Request item status field for a specific object (the same values are supported - field name/JSON path to the field storing the status, it can also include placeholders in curly brackets). If not provided, the value from the configuration is used.

  • JobExternalIdentifierPropertyName
    The name of the property/attribute from the result values used to resolve the special placeholder [JobExternalIdentifier]. This placeholder is resolved with the ID from the parent item and can be used in provisioning tasks to add a link.

Task mappings​

The connector sends requests to create issues for both jobs and tasks. To distinguish between mappings, the object for a job must have a defined object detail in the data model (UseForJob with value – true). In the task mappings, you can set a mapping target - an object for either a job or task (an example for Jira):

For single-value mappings, the value is taken from the first task. For multi-value mappings, all values are added (if it is an array - added as separate items, if text – a concatenated string).

Retries for partial success​

There might be occurrences when the creation of the ticket (either a parent or a subtask) is successful, and then the creation of the issue for the provisioning task fails. REST API usually doesn't provide a database-like rollback mechanism. Using the Create operation again will cause duplicated items to appear. Omada sets CreateIfNotExists in the mappings by default to prevent this problem. The connector always checks whether a ticket with a specific ID exists, and then creates it only if it does not. Links between subtasks and parents are correctly assigned, regardless if they are created in the same attempt or in the retry operation.

The mapped operation should always use CreateIfNotExists (or Create if the issue detection functionality should not be used). The connector always creates a new ticket in the target system - it can use the source operation to explain what action should be performed. Even if the source operation is Delete, the mapped operation will perform CreateIfNotExists (for example, it will create a ticket to remove access with the description Remove access to <resource> for user <ABC>).

important

To use CreateIfNotExists properly, you need to find a way how to check whether the object exists (it depends on the REST API). We recommend filling a field with a unique value (from Omada tasks), and then searching for this ticket. If this operation is not supported by the target API, use the Create operation.