Adding an API call to a task

Sponsor Administrators can set up tasks to call REST APIs. When the partner runs an activity with an API dialog, the response from the API is passed to the API server in the sponsor's organization.

1. Sign in to the PEM Partner Provisioner as a Sponsor Administrator.
2. Select Activities > Definitions.
3. Edit an existing activity or start a new activity.
4. Right-click a task in the task flow to which you want to add an API and select Define.
5. Drag the API component onto the canvas. The API window is displayed.
   1. In the Name field, type the API name.
   2. In the Note field, type the API description. Click OK.
      The API is added to the workspace.
6. Right-click the API component and select Define.
   The Define window is displayed.
7. Enter information in the following fields:
   1. API Configuration - If an API is configured under Setting > API Configuration, a list of existing API configurations is displayed in this field. You can also view the shared API configurations. Select the API configuration to use.
      Note: Configure the API before adding any API to a task. For more information, see Creating an API configuration.
   2. Host Prefix - Select the check box to add host information that corresponds to the selected API configuration to the URL field. If the check box is not selected, the URL field does not have the host information added.

      By default, the check box is selected.

   3. URL - After you select an API configuration, and if the Host Prefix check box is selected, the protocol, host, and port for that configuration are populated. Provide the remaining part of the URL. To map the URL, click ....
      Example: https://198.51.100.3:9450/mrmws/sponsors/user1/partners

      Note: The URL can be different based on your deployment option. For more details about the URL, see URL for accessing IBM PEM and APIs.

      If the Host Prefix check box is not selected, and the host information is not added to the URL field, you must provide a complete URL.

   4. Request Method - Choose the request method such as POST, PUT, GET, or DELETE. For example, POST.
      Note: If you select GET or DELETE, you cannot pass the request. Instead, you must include parameters in the URL.
   5. Headers - Click Edit to edit the header information.

      Click Add to enter the name and values.

      Click Remove to remove the name and values.

      Note: You cannot pass parameters to the header. For example, accept=application/xml
   6. Input/Output Format - Choose the format to be input and output, either XML or JSON.
      Note: The format must be the same for both input (request) and output (response).
   7. Escape Request - Select this check box to automatically escape unicode or special characters in mapping. For example, in either JSON or XML, when you map a request for which the substituted values contain special characters, the special characters are automatically escaped.
   8. Request - Enter a valid code to pass when the activity starts the API. To map attributes of XML or JSON to context parameters, click the mapping button (...). A mapper window opens.
      Tip: You need to enter code before clicking the ellipsis (...), or the mapper screen does not appear.

      A tree with your XML or JSON code for the Request is provided. When you click any node in the Request tree, the Context side of the window appears, and is populated with the context so you can update the code with mapped parameters. Leaf nodes (both Element and Attribute) and Text nodes (that is, a Non-leaf node with text as the value) can be mapped. If you enter any special character, ensure to escape the special character. For example, if you enter don't, to escape the single quote special character, enter don\'t.

      Note: When you map a component to an API request, for some API request components such as API Response, XSLT output, and so on, you can select the text or node mapping. For other API request components, the component is by default mapped to text or node. If the mapping is of type text, the text of the node is returned. Otherwise, the node is returned.

      When you click OK, updated code is populated in the field.

      Example: <create userId="" firstName="" lastName="" question="" answer="" officePhone="" nameOfCompany="" streetAddress="" city="" country="" zipCode="" headOfficePhone=""/>

      With a GET or DELETE request, the Request field is disabled.

      You can also map multi-select table components to a request. The root node can be mapped to AllRows or SelectedRows of a multi-select table. The child nodes can be mapped to the column headers of the table components. The root node should be mapped before the child nodes are mapped. Multilevel table component mapping in API request is not supported.

      Example:

      <b>
            <Name>${/Parameters/ActivityContext/Task[@Name="P"]/Dialog[@Name="D"]/Table[@Name=
            "C-1"]/AllRows/Column[@Name="Name 
            Textbox1"]/text()}</Name><Value>${/Parameters/ActivityContext/Task[@Name="P"]/Dialog[@Name=
            "D"]/Table[@Name="C-1"]/AllRows/Column[@Name="Name
            Textbox1"]/text()}</Value><Select/><c><test1>${/Parameters/ActivityContext/Task[@Name="P"]/Dialog[@Name=
            "D"]/Table[@Name="C-1"]/SelectedRows/Column[@Name="Name
            Textbox1"]/text()}</test1>${/Parameters/ActivityContext/Task[@Name="P"]/Dialog[@Name=
            "D"]/Table[@Name="C-1"]/SelectedRows}</c>${/Parameters/ActivityContext/Task[@Name
            ="P"]/Dialog[@Name="D"]/Table[@Name="C-1"]/AllRows}
         </b>
       </a>

      The b node is mapped to AllRows and the child node of b Name is mapped to the columns of the table component. Another child node of b and c is mapped to SelectedRows and the child node of c is mapped to the columns of SelectedRows. During the processing of the activity, the values for only child node b are replaced.

      A JSON request is a string pattern and the request that contains Number or Boolean is evaluated as string only. You can manually convert these Number or Boolean by using the Number or Boolean annotations in the request.

      Examples:

      • A JSON request that contains string can be converted by using the Boolean annotation.
        Original request:

        {"isNumber":"${/Parameters/ActivityContext/Task[@Name=\"p\"]/Dialog[@Name=\"D1\"]/TextBox[@Name=\"C-1\"]/text()}"}

        Converted by using the Boolean annotation:

        {"isNumber":"$(Boolean){/Parameters/ActivityContext/Task[@Name=\"p\"]/Dialog[@Name=\"D1\"]/TextBox[@Name=\"C-1\"]/text()}"

      • A JSON request that contains string can be converted by using the Number annotation.
        Original request:

        {"rollNumber":"${/Parameters/UserContext/SponsorName/text()}"}

        Converted by using the Number annotation:

        {"rollNumber":"$(Number){/Parameters/UserContext/SponsorName/text()}"}

      Also, a complete XSLT output can be mapped as an input for an API request and a complete API response can be mapped to an XSLT input. For example, an activity that has task "A" with API and XSLT dialogs, for which the API response is <department><name>ABC</name><address>1st Lane</address></department> to retrieve the output as the complete XML, the XSLT input request should be provided as ${/Parameters/ActivityContext/Task[@Name="A"]/Dialog[@Name="API"]/Response/department} without providing any XML tags.

      Note: This mapping is applicable only for XML.
   9. File Attachment - Click Select to upload or select a file from the list. The file is passed as input to the API. To upload a file:
      1. Click Upload. The Upload File window is displayed.
      2. Enter a Name.
      3. Select the Encrypt check box to encrypt the file in the database. Clear the Encrypt check box to disable file encryption in the database.
      4. Click Browse and select the file to upload. Click Upload.
      5. Click OK to close the confirmation message, and OK again to return to the Define window.

         To map the file to a FileUpload node, click the ellipsis (...). A window with an XML or JSON tree opens. Select a FileUpload node.

         Note: In the tree, only FileUpload components in the activity are listed.
         You can modify the file to FileUpload node mapping as follows:

         • Click ... and select another FileUpload node. This selection modifies the file to FileUpload mapping.
         • Click Select to upload or select a file from the list. This selection modifies the FileUpload file to file mapping.

         With a GET or DELETE request, this field is disabled.

   10. Sample Response - Provide the sample response that you expect from the other system.
       Example: <?xml version="1.0" encoding="UTF-8"?> <success response="" rowsAffected=""/>

       Restriction: Due to generic XML and JSON limitations, the sample response must not contain element or attribute names that starts with a number or contain space. However, if the sample response contains element or attribute names that starts with a number or contain space, the JSON content is not allowed for mapping.
   11. Call in Test Mode - Select the check box to call the API when the activity is run in test mode.

       If the check box is not selected, the API call does not occur in Test Mode and parameters in the Sample Response field are used by the next task or dialog that is mapped to the parameters in the Sample Response.

8. Click OK.
   The fields are validated and updated. If the XML or JSON code that was entered is not valid, you get an error when you try to save the task.
9. Click Save as draft. A confirmation message is displayed, click OK. Otherwise, click Task Flow (with the name of your task) to finish the rest of the flow. Make sure to connect all the components in the order you want them to flow.
10. If you are finished designing the activity, click Mark as final.
    The activity designer validates the activity definition and if there are errors, error messages are displayed. If the validation is successful, then the activity definition is complete.