Specifying details for an API element

To model a workflow that makes an ION API call:

  1. Start ION Desk and navigate to the workflow modeler.
  2. Add a workflow step of type API.
  3. Define properties of the workflow step and prepare the call to the API.
    Click the ION API tab. Specify this information:
    Name
    The workflow step name that is displayed in the workflow diagram. The same name is displayed in the Workflow Activity Locator. Define properties of the workflow step and prepare the call to the
    Description:
    The step description that is used for modeling purposes.
    Product
    The name of the application that exposes the ION API to call, as it was provisioned in Infor Ming.le ION API. The product name is selected through the operation selection dialog.
    Operation
    The ION API operation to call.
    Click SELECT to open the dialog that helps searching for an ION API operation using the ION API metadata. First select a product from the drop-down, then type in a search string and click the search icon. If the operation you are searching for is not in the list, click Show More. You can use the browser search function to refine the search within the resulting list of operations.
    Service Account
    Import the service account obtained from Infor Ming.le User Management that grants permission to call the selected API operation.

    Click IMPORT to select the service account file and load it into the workflow step. After import, the description of the service account is displayed. You can use the same service account in several workflow steps. The credentials of this service account are used in these situations:

    • When calling the API from ION Desk, define properties of the workflow step and prepare the call to perform a Test API Call.
    • At runtime, when the workflow performs the API step.
    Note: When exporting a workflow model that contains an API step, the service account that is used by this step is not exported. This is intentional, to prevent that service accounts are misused. After importing a workflow, you must reconfigure the service accounts in each API step.
  4. Specify the request parameters.
    Click the Request Parameters tab. This tab is populated with the list of request parameters required to make the API call after an operation is selected on the ION API tab. These parameters are listed in a table with these columns:
    Name
    The operation parameter name as defined in the API metadata. An asterisk indicates whether it is required to pass a value for this parameter.
    Description
    The operation parameter description as defined in the API metadata.
    Data Type
    The operation parameter data type that was defined in the API metadata.
    Parameter Type
    Can be PATH or QUERY. Path parameters are used to build up the operation path and may not be null or empty. Query parameters are used to pass on additional values and may be optional or empty strings.
    Value
    Specify a constant value to use in all API calls for the API parameter on this row. Select the radio button in this column.
    Workflow Parameter
    Select a workflow parameter to pass a value from the workflow to the API operation parameter when calling the API. This is required only when the API operation parameter is required. If you do not select a workflow parameter, then the null value is used in the mapping.
    Note: 
    • You can map a workflow parameter or a constant value to the request parameter of an API operation. The radio buttons in the Value and Workflow Parameter columns help to enforce this choice for each row. The default selection is workflow parameter.
    • The mapped parameters or values are used at runtime as input values to call the API. All workflow parameters are converted from any data type to string. This table shows the conversions that are performed by default:
      Data type Formatting
      Integer and Decimal Decimal separator is dot "."

      There is no number grouping character
      Strings (including User, Group, Hyperlink, Code) Space is encoded as %20

      Values are not trimmed
      Boolean Expressed as "true" or "false"
      Date and DateAndTime UTC format is used YYYY-MM-DDTHH:MM:SSZ, for example: 2011-10-24T22:46:00Z
  5. Specify the request body.
    Click the Request Body tab. This tab contains the properties of the request details of type body. If the selected operation does not have a request body, the controls on this tab are disabled.

    If the selected operation has a request body, this information is available:

    Name
    The name of the parameter of type body that was defined in the API metadata.
    Description
    The name of the parameter of type body that was defined in the API metadata.
    Content type
    Select the content type to send as request. If the API metadata specifies that this API operation can accept several content types, these are listed in a drop-down. Possible values are application/json, application/xml, text/xml, and text. If the API can accept only one content type, this is pre-selected and cannot be changed.
    Body
    This is an input text box that must be filled in with data that is consistent with the content type. If the request body is required for this operation, you may not leave this text box blank.
    If the request body is optional you can choose to perform these actions:
    • Specify the Body text box with valid data. This information is used as request body for the API call.
    • Leave the text box blank. An empty string value is used as request body for the API call.
    If the model schema is described in the ION API metadata, you can generate an example body. To fill the request body with a sample, click EXAMPLE. This button is available for these request content types:
    • application/xml
    • application/json
    You can use parameter placeholders in the data for the request body. To specify a placeholder, press Ctrl+Space or Ctrl+Alt+Space. A list of workflow parameter names, structure names, and the $notes() placeholder is displayed, from which you can select one entry at a time. The displayed list of parameter placeholders is divided, by lines, into 3 parts. The first part contains parameters, that are sorted alphabetically. The second part contains $notes(). The third part contains structures, bold and sorted alphabetically.

    Alternatively, use these placeholders:

    • $value(<parameter name>)

      Use this syntax to insert a placeholder for a workflow parameter. The <parameter name> must be an existing workflow parameter. At runtime, the placeholder is replaced with the value of this parameter, converted to string. The same data type conversions are applied as for request parameters.

    • $escape($value(<parameter name>))

      Use this syntax to escape special characters in a string or in the value of a workflow parameter, for example $,/”,<,>,*,&,< and so on.

    • $structure(<structure name>)

      Use this syntax to insert a placeholder for a workflow structure. The <structure name> must be an existing workflow structure. At runtime, the placeholder is replaced with the value of this structure.

    • $notes()

      To insert a placeholder for the notes that are collected in the user tasks that are executed up to the current step in the workflow. At runtime, the placeholder is replaced with all the notes that are listed in a predefined structure.

    Note: The $structure(<structure name>) and $notes() placeholders should be used only in the request body of a POST or PUT method. These assumptions are made:
    • The method accepts a request BODY of the application/json or application/xml content type.
    • The BODY contains an element that matches the definition of the workflow structures or the notes.
    For structure definition and notes definition sample JSON files, see KB 2062292 on the Infor Support Portal.
    If you are using parameter placeholders for the request body, these are listed as input parameters on the Test tab. Therefore, you can provide test values and validate the API call works with the specified request body.
    If you are using structure or notes placeholders for the request body, these are not listed on the Test tab. When testing, sample data for the structures and notes is automatically generated.
  6. Specify the output parameters.
    Click the Output Parameters tab. On this tab you can map API responses to workflow parameters so they can be used later in the workflow.
    On this tab you can select the Response Content Type if the API can return several types of responses. Possible values are application/json, application/xml, text/xml, and text. If the API can return only one content type, this is pre-selected and cannot be changed.
    Here you can also specify the output mapping. Use the ADD and REMOVE buttons to specify as many mappings as required. The table for the output mappings has these columns:
    Response
    Select from CODE, HEADER, BODY. These are API response types that can contain various information:
    • CODE is a number which usually indicated if the API call was successful or not
    • HEADER is a property list that contains header information such as content-type
    • BODY contains the API response data, usually as a JSON or XML structure. You can extract values from this type of response to map into workflow parameters using a Path.
    Path
    When the response is a structure, specify a Path to extract a specific value. If the response BODY is a JSON message, you must specify a JSON Path. If the response BODY is an XML message, you must specify an XPath. For a response of type HEADER, the Path must be a header name. See “Specifying a path for output mapping” for details.
    Optional
    Select this check box if one output mapping may be skipped if the specified Path does not yield a value from the API response. See “Avoiding workflow failure”.
    Workflow Parameter
    Select the workflow parameter that contains the value that is extracted from the API response. The value that is extracted from the API response is converted to the workflow data-type.
    Note: 
    • The Path is not required in these situations:
      • response type CODE
      • response type BODY when Response Content Type is text.
    • The UI does not validate if the Path you typed is correct. Use the Test tab to verify if your configuration is correct.
    • When you change the response content type after you defined output mappings, all mappings are removed.
  7. Test the API call execution.
    Click the Test tab.
    On this tab you can test the API call execution and the mappings to the workflow parameters. To use the test tab, all the previous configurations must be completed on the ION API, Request Parameters, and Output Parameters tabs.
    The service account that is imported on the ION API tab is also used to perform the test call.
    TEST button
    Fill in values for the Input Parameters displayed on this tab and click TEST. If the API call is successful, the results are visible in the Output Parameters section on this tab. If the call did not succeed, an error is reported in a message dialog.
    Input Parameters tab
    After mappings are completed on the Request Parameters tab, the workflow parameters used as input for the API call are listed here. If parameter placeholders are used in the request body, then these are also listed. Specify values for these parameters to test the API call.
    Output Parameters tab
    After mappings are completed on the Output Parameters tab, the workflow parameters used as output for the API call are listed here. If the API call test is successful and the output mappings contain correct paths, the values for the output parameters are displayed here.
    Note: The ION Desk time-out is applied when waiting for the API test call results. If the API does not respond within this time-out, the test fails. You cannot change the time-out configuration for the Test API call from ION Desk.
  8. Specify runtime settings.
    Click the Settings tab. On this tab you can specify preferences for the execution of the ION API call at runtime.
    There are two sections:
    How to handle errors
    Here you can choose how to let the workflow behave when the API call failed. You can choose for:
    Continue workflow without changing parameters.
    Choose this option if the API call can be ignored and the workflow must continue.

    Optionally, you can select the Response status code check box and specify a workflow parameter of type string, integer or decimal. If the API call is not successful, the selected workflow parameter contains the response status code returned by the API.

    The workflow fails
    Choose this option if the workflow should not continue if the API call fails.
    Advanced Settings
    In this section you can modify the settings for the API call time-outs. There are two values:
    Retry Time if ION API is Unavailable (seconds).
    This is the period of time in which ION tries to restore the connection to ION API. The default period is 600 seconds (10 minutes) in which ION retries to connect.
    API Call Timeout (seconds).
    This is the interval of time to wait for a response from the ION API call. The default value is 600 seconds (10 minutes).
  9. Save and activate the workflow.