Developer Guide

Overview

This document outlines the steps for creating a connector using the External Connector Framework (ECF). Prior to jumping into the various details of connector creation, let's look into a high-level overview of the steps involved. The above flow diagram lists out the various steps of the development lifecycle.

Pre-Requisite:

1. Identify the target application which needs to be integrated using ECF.
2. Identify your preferred language for development and setup corresponding IDE.
3. Ensure required libraries are installed for customizing the connector.

Generate Server:

1. Download OpenAPI Spec file.
2. Open Swagger Editor in web browser by navigating to swagger.io
3. In the editor window, click on File --> Import file and select the OpenAPISpec.yaml from your system.
4. You should be able to render the API specification on right panel.
5. Now go to Generate Server -> select your preferred development language
6. This will generate a zip file.

Start Server:

1. Unzip the downloaded server zip file.
2. Start the server, This step may vary depending on language which was selected to generate the server in earlier step.
3. You should be able to get successful message around server is running and swagger-ui available with URL information.

Note: Default generated server uses http protocol and starts on 8080 port, in case there is already some other application running on this port, server startup may fail. You need to change server port to other than 8080 and then start same. Configuration file which contains port number should be available under unzipped folder.

Explore ECF API Specification:

1. Go to swagger UI URL. You should be able to access ECF API specification.
2. You can explore the available APIs. This is useful as in further steps when you customize the connector you need to ensure that connector follows the endpoint definition, response format specified as per this specification.

Customize the connector:

1. Import the generated project in your preferred IDE.
2. Customize the connector as per your requirement, implement logic for authentication, for each API operation handle request body processing, response generation etc.
3. Once complete customization is done.
4. Start the server.

Recommendations:

1. As part of customization you should also setup ssl certificate to enable running the server over https.
2. You should implement pagination for import operations.

Unit Testing:

1. Go to swagger UI URL. You should be able to access the API specification as per your custom connector.
2. You can use "Try it out" feature of Swagger UI to perform quick unit testing of each implemented endpoints.
3. Ensure the responses are in ECF specification format.

Note: You may choose to remove operations which you may not want to perform, however for operations which you want to perform it should follow the Saviynt provided ECF API specification.

Integrate with EIC:

Once custom connector unit testing is successful, you should work with EIC administrator for this step. In this step, you will configure EIC artifacts needed to integrate the ECF based custom connector with EIC:

Import ECF connection transport package:

1. Download Connection Template Package file.
2. Login to EIC.
3. Go to Admin -> Transport -> Import Package.
4. Select the downloaded package file in "Choose package to import *" option and provide business justification.
5. Click on View Summary. Summary page should display connection object named ECF.
6. Click on Request and then Submit to confirm import.
7. Initially status will show In Queue, You can refresh the status, it should be Success in sometime, this will confirm transport package with ECF connection is successfully imported.
8. You can validate same by navigating to Admin -> Connections -> Search for ECF.

Configure ECF Connection:

1. Go to Admin -> Connections -> Open the connnection named ECF.
2. Rename the connection name: Default name is ECF, however you may want to import more ECF based connections later on, when you import connection transport package next time that will replace your existing connection with name as ECF, hence this is important to change connection name to ensure your connection is not overwritten later on.
3. Configure ConnectionJson, copy and paste below json (replace https://<HostName>:<Port>, with valid hostname and port details):

{
  "authentications": {
    "userAuth": {
      "authType": "oauth2",
      "url": "https://<HostName>:<Port>/api/v1/login",
      "httpMethod": "POST",
      "httpParams": "{}",
      "httpContentType": "application/json",
      "httpHeaders": {
        "Content-Type": "application/json"
      },
      "authError": [
        "USER_AUTHENTICATION_FAILED",
        "PARTNER_AUTHENTICATION_FAILED",
        "AuthenticationFailed"
      ],
      "errorPath": "errorCode",
      "maxRefreshTryCount": 5,
      "tokenResponsePath": "access_token",
      "tokenType": "Bearer",
      "authHeaderName": "Authorization",
      "accessToken": "Bearer abcd",
      "retryFailureStatusCode": [
        401
      ]
    }
  }
}

4. Update other connection parameters, replace https://<HostName>:<Port>, with valid hostname and port details.
5. Review STATUS_THRESHOLD_CONFIG parameter and update as per requirement. As per ECF specification, account status from target should have been mapped with customproperty11, however if your API response has account status mapped with a different EIC Account Attribute, please update same as statusColumn. Also specify all possible values that indicate the active status of the accounts in the target application in activeStatus field.
6. There is no need to update any other configuration on connections page, these are preconfigured as per ECF specification.
7. Save and Test connection.

Create Security System and EndPoint:

1. Create a security system and use connection created in previous step as Connection and Provisioning Connection.
2. Create an endpoint for security system created in step 1.
3. Configure workflows as needed for provisioning operations.

Integration Testing:

As part of this step, you will perform integration testing to ensure that the EIC & ECF based custom connector integration is successful.

Import validation:

1. Configure import job for users/accounts/access: Configure and execute the import jobs for importing user/accounts/access from target application.
2. Validate that users/accounts/access and their relationship is successfully imported and correctly represented in EIC.

Provisioning validation.

1. Use ARS/Rules to request various operations on accounts.
2. Corresponding pending task should be created.
3. Configure and execute WSRetry provisioning job and validate if operation is performed as expected to target application.
4. Ensure EIC is correctly representing the state.

As part of integration testing perform testing of all required operations which are supported by your custom connector through EIC. Successful completion of same will conclude that connector development is succesfully completed.