Create App Connector

This article contains the following topics:

App Connector

The New App Connector button helps you create and manage your app connectors. The app connector supports both cloud-based and on-premise apps. Each connector performs various operations. Operations describe the list of HTTP, REST API's exposed by the remote system. Each operation is identified by a URL end point, input, and output parameters. These operations can be used in processes or workflows. During the process of automating workflows and adding connectors to perform operations, you need to set up connector credentials. In the Credentials tab, you can define the credentials that each connector requires to connect to external systems. For more information about how to set up connector credentials see Manage Connector Credentials .

You can navigate to this tab by clicking WORKSPACES> AUTOMATION> Automation Center> C onnector Library> New App Connector.

The process of creating an App connector consists of the following steps:

1. Understand the API of the target application for which you want to build an app Connector.
2. Define an App connector
3. Configure Authentication Parameters and Validate
4. Setup one or more connector operations
5. Use App connectors in workflows

These steps are described further in the following topics.

Understand the API of the target application for which you want to build an App Connector.

The first step to define an app connector is to understand the API of the target application for which you want to build an App connector. You require the following information:

1. API URL - The URL of the target application.   
2. Authentication type- The Authentication types that are supported are Basic, None, and Advanced.
3. Operations - Operations describe the list of API invocations on the remote application. Each operation is identified by a URL end point, input, and output parameters. 

Define an App Connector

Set up the basic properties of your app connector.
Follow these steps:

1. Navigate to WORKSPACES> AUTOMATION> Automation Center> Connector Library.
2. Click New APP Connector.
3. Provide the basic details about the connector in the Basic Properties section. Basic details include the following:
   
   • The App connector name.
   • The API Version. An App Connector is built for a specific API version that is published by the target application. Input/output parameters, operations may change across API versions. If you have multiple connectors for the same app for different versions, you can use this field.
   • The connector description explains what the connector does.
   • The connector type. Your connector could be available on cloud or on-premise. 
   • The Base URL for the connector. This URL is used by Serviceaide Intelligent Service Management to connect to the service. Select the type of user authentication that you want to use for your connector. Intelligent Service Management supports Basic and Advanced authentication.
   • The API format. ReST API request/response formats (content type) can be JSON or XML.
4. Set up the connector operations.
5. Click Save.

Configure Authentication Parameters and Validate

 Intelligent Service Management supports, None, Basic, and Advanced authentication. Every HTTP rest call needs authentication. After you fill in the basic properties you can configure authentication parameters for your connector.

• Basic Authentication: A Simple authentication technique that is supported by HTTP. Basic Authentication requires the username and password.
• None: None This does not require authentication.
• Advanced Authentication: Advanced Authentication is used with applications that have token based session management. In this model, end-user first obtains a session token by logging into the application and then uses that session token to access other resources in that application. It is important to use the same security token parameter in authentication and subsequent operations to ensure that both are in the same session. You can review the Rally Connector to understand how to specify advanced authentication.

• • Setting up authentication parameters does not create credentials. Credentials can be added in the Connector Library tab or Design Studio. Validating authentication parameters results in the creation of the first credentials. You can use the first credentials for all subsequent operations during definition. This credential can also be used during a workflow execution.

• • Once a connector is saved, its authentication type cannot be changed.

 Follow these steps:

1. Navigate to WORKSPACES> AUTOMATION> Automation Center> Connector Library.
2. Click New APP Connector
3. Select the type of user authentication that you want to use for your connector.
4. Click the link View test output and select parameters.
   A pop-up appears which contains an authentication call response in JSON/XML format.
5. Select token from the response output to pass the parameters to the next operation call. Click Select Parameters.
6. Automatically the parse string appears in the text box as an Output parameter in the Output Parameters tab.
7. Select the parameters that the connector passes from the authentication call to the next operation calls.
   Note: You can provide a user-friendly name to this parameter in the Name to identify box which can be used in subsequent operation calls.
8. Click Save.
9. (Optional) Click Validate.
10. In case of basic authentication, validation is automatic if the username and password are input accurately.
11. In case of advanced authentication, a popup is displayed with the JSON/XML response output. An Accept and Reject button is displayed. Click Accept and the status changes to Validated
12. (Optional) Click Use Basic Authentication, if an advanced authentication needs Basic authentication too.
13. (Optional) Click Send Cookies, if an advanced authentication requires to send cookies.
    

Setup one or more Connector Operations

 Define the operations that your connector can perform. Operations describe the list of API invocations on the remote application. Each operation is identified by a URL end point, input, and output parameters. These operations can be used in processes or workflows.

Follow these steps:

1. Navigate to WORKSPACES> AUTOMATION> Automation Center> Connector Library> New  App Connector.
2. Click New Operation. 
   A new operation is added in the left pane. You can define the properties of the operation in the right pane. A default name is automatically assigned to the operation. You can edit this name in the Operation Name field.
3. Provide a description of the operation in the Description field.
4. Provide the Sub URL for the operation. Every ReST API is identified using a unique URI. This URI is captured as Sub URL. Example: /ReST/v1_1/templates
5. Select the HTTP method that the operation invokes. Example: GET, POST, PUT, and DELETE.
6. Click Next.
7. Define the input parameters and output parameters for the operations.
   
   1. Input Parameters: Provide the keys that are required by the API. Provide values for the URL query parameter and the HTTP header field. Select how the HTTP Body data is treated. In the Body drop-down select Form data or Raw Data.
      Each URL Parameter has three fields. First two fields capture key, value pairs of a URL parameter and the third field is for providing user readable name for the key. This value is used when this field is displayed in the service request. Click the + to add more parameters.
      
      • Select Form data and enter the Key, Value, and user Identifiable Name, in the key value payload form.
      • Select Raw Data and enter the JSON/XML payload information.
      • Provide all the test values of the API in the Value text box. The value in the User Identifiable name creates an input parameter for the connector. The input parameter appears in the data mapping. Provide the actual URL Parameter or Header key in the URL Parameter or Header text box.
      • To customize the content of the sub URL or payload and create input parameter values which are provided at the workflow creation time then use format {{VARIABLE_NAME:VALUE}}
   2. Output Parameters: Provide the keys and values for the output of the operation.
      • • Click View test output and select parameters the XML/JSON. You receive a response in tree format. You can use this response to create output parameters by expanding the tree and by selecting a value.
        • Every output parameter has a Name to identify, which could be a user-defined name for that connector operation. You can use this user-defined name in a workflow, if you need to send an output of step, as an input to the other step.
8. At any point, click Save to save your operation details only. To save the new connector, click Save at the top of the page. Click Next to move to the next tab. Click Reset to clear all details.
9. Add more operations as necessary.
10. Click Save at the top of the page

Note: Validate the operation before you save. Click Validate and you can see a popup with the output response and an Accept and Reject button. Click Accept and the status changes to Validated.

Your app connector is saved and added to the connectors list in the Available tab in the Connector Library. You can now use this connector and create workflows, for more information  see How to create a Workflow. The Workflow that is designed can now be linked to a process flow in the process designer, for more information see Use Automation Steps. 

Use App connectors in Automation workflows

You can use the App connector to automate tasks as part of the Automation workflow creation and while creating a process flow in  the process designer.

Examples of u sing App Connector in Automation Workflows (Adhoc repetitive usage)

IT Support Personnel receive a request to repair a laptop

• Use an automation workflow that queries Dell service for warranty details and sends the information over email to the IT support personnel.
• The support personnel can decide to either send it for repair or suggest procuring a new one.

Examples of using App Connector in Process Flows (Ticket fulfillment process)

• Once the ticket is received, the analyst can trigger the automation step to query dell service and update warranty details on the ticket.
• The ticket can be closed with suggestion to either procure new laptop.
• The ticket can be closed once the repairs have been done.