When our integration platform is used as an embedded environment, you receive a mini-version of our platform with abilities to:

User registration

Once your user would like to activate one or multiple of your integrations on your website, you would need to create a new sub-user account under your platform account. These will be "virtual users" that belong to your account, you will have the rights to manipulate their accounts, tasks and read the integration statistics on your sub-user behalf.

New users can be added following the format below:

{
   "first_name": "John",
   "last_name": "Doe",
   "email": "test@example.com",
   "password": "secret",
   "company": "Doe & Partners"
}

In the example above first_name, last_name, email and password are required fields. After submitting user information, our system will create unique user id and api_secret for this particular user. Last one is the API Key which is used to authenticate each request of this user. For an in-depth reference check the API documentation for Create a User endpoint.

Add credentials for users

Now we need to add credentials for your users in order to authenticate data from your end-users. In our system we call this process Add new account. Every user in your embedded environment can add his/her credentials to many services and applications that you provide (following the above use case scenario - Salesforce, SugarCRM, MS Dynamics CRM, etc). When your users add credentials for an account, they need their own unique API Key to do this.

Basic structure of adding credentials can look like this:

{
  "name": "My Dropbox account",
  "type": "dropbox",
  "keys": {
     "oauth": {
         "key": "some key"
      }
   }
}

Newly added credentials for any service should be checked for validity using one of the supported authentication methods through the platform.

When our integration platform is embedded it also includes several existing Base Components, you should know that each component comes with its own predefined authentication method. For example if you take Salesforce, then the authentication is done via OAuth 2.0. Other components might have the same or different methods.

If you provide your own component, you would need to setup a suitable authentication method in it to verify the credentials.

Create tasks

Every integration task that can be created using our integration designer can also be created using a specific API call. To learn about specific command calls to be used in this embedded environment you can check our Rest API documentation.

Before looking into the Task structure, it is worth mentioning that when the task is submitted into the App, in return you get a {TASK_ID}. The answer is as simple as this:

{
    "id":"55083c567aea6f030000001a"
}

Here we will explain the JSON structure used to submit tasks. Let us begin with a simple WebHook to MailChimp integration flow. The basic structure of the task is presented below:

{
  "name" : "WebHook to Mailchimp",
  "cron" : "*/3 * * * *",
  "nodes" : [
      {
        "function" : "platform/webhook:receive",
         "config": {
             "payload": "email,first,last"
         }
      },
      {
         "function" : "platform/mapper:map",
         "config": {
             "mapper" : {
                "lastName" : "{{last}}",
                "firstName" : "{{first}}",
                "salutation" : "{{salutation}}",
                "email_type" : "html",
                "email" : "{{email}}"
              },
             "lookup_tables": {
                 "salutation": "lookup-table-id-to-be-used-for-salutation"
              }
          }
       },
       {
         "function" : "platform/mailchimp:subscribe",
         "account_id" : "54536902230d250700000016",
         "config": {
             "listId" : "8779dd762e"
         }
       }
  ]
}

Follow closely the presented JSON structure in this example if you wish to submit your integration tasks via an API call.

  • name is exactly the name of the integration flow "Webhook to Mailchimp".
  • cron is an optional field which can be used to schedule your tasks. More information about the usage can be found in the cron's own Wikipedia article.
  • nodes is an array structure including all the description necessary to run the flow. Inside the nodes structure the particular components are placed. Each component is described with function, config and account_id if applicable. Let us consider again the case of integration flow "Webhook to Mailchimp".

WebHook

  • function : "platform/webhook:receive" would mean that this particular component is from platform team with a name of webhook which has a receive trigger.
  • "config" : {"payload": "email,first,last"} would indicate the configuration of WebHook component with a payload of simple CSV list. In this particular case the beauty of WebHook component enables almost limitless structures to be passed along as payload.

Mapper

  • "function" : "platform/mapper:map", is the Data Mapper component which comes by default and can not be modified. This component is mapping the fields according to the information received from our WebHook component.
  • "config": { "mapper" : { ... }}, contains the configuration of the mapped fields received in payload of WebHook. It also contains other fields which are required or possible to process for the next stage of the integration flow to MailChimp. For example we can specify the email_type to be of html format. We have also field called salutation which can contain a simple value or it can also accept values from a lookup_table.  
    • lookup_table can be submitted separately to contain several values to be replaced during the processing. For example with this ability one can provide translation from Mr/Mrs English salutation into Herr/Frau German salutation.

MailChimp

  • "function" : "platform/mailchimp:subscribe", is the action in MailChimp component which will add every value to a particular list of yours - subscribing them to a particular mailing list. As with other cases this particular component is from platform team.
  • "account_id" : "54536902230d250700000016", in this case would be the ID of credentials submitted and authenticated earlier. In our system every authenticated credential record has it's own ID which is given every time a credential is successfully submitted and authenticated.  
    • "config": { "listId" : "8779dd762e" } is the name of particular list to which every new records is added.

Activating and stopping the tasks

The new generated tasks will be added in an inactive state which is actually better for reviewing and editing the task before activating and starting the integration flow. After the task has met the specifics of the user, it can be activated again by using a call to API.

Activate Task

curl -X POST https://api.platform.address/v1/tasks/start/{TASK_ID} \
   -u {EMAIL}:{APIKEY}

Simply sending your {TASK_ID} and then your user credentials {EMAIL}:{APIKEY} via HTTP POST allows to activate your desired integration flow (task):

{
  "id": "5538bd9646208d02b3000005",
  "status":"active"
}

Along with the ID of your task you receive the current state of your task. Here we receive confirmation that our task has been activated.

Stop the task

curl -X POST https://api.platform.address/v1/tasks/stop/{TASK_ID} \
   -u {EMAIL}:{APIKEY}

In this case we send the same information via HTTP POST using another address that has been specifically set for stopping the particular integration flow (the task):

{
  "id": "5538bd9646208d02b3000005",
  "status":"inactive"
}

Here we receive confirmation about inactivity of our task.

Monitor

The monitoring of the task will be done using a separate interface. The end-user will be given basic information about the execution and completion of the task. On the contrary, as an App provider you will be able to monitor all the tasks from your users completely and provide feedback if necessary.