This article will show you how to create an RKVST App, this article will show you how to use it in a Zap.
To create your own App you will need access to the Zapier Developer portal and you will need to be able to write JavaScript code.
Zapier is an automation platform that allows users to link thousands of products together to create new workflows without writing code to link the product APIs.
It works using the concept of a Trigger event that results in a Action response. Each product is represented by an App and each App can include one or more Trigger and Action functions.
The platform allows you to take a Trigger function from App A and link it to an Action function from App B. This forms what is called a Zap.
The App Components.
There are three main sections that can be configured for every App.
- Authentication. This must be configured, it allows the Zapier App to make REST API calls to RKVST.
- Trigger. It is not compulsory to configure a Trigger but we will cover setting up a Trigger for the creation of a new Asset on your RKVST tenancy.
- Action. This is also not compulsory. We will set up an Action to create a new Asset on your RKVST tenancy.
Authentication.
1. Log into your RKVST tenancy and create an app registration. This will allow Zapier to make a REST API call for an access token using the client ID and secret.
IMPORTANT: You have one chance to copy the secret when you create the app registration. If you leave or refresh the page it will be hidden and must be regenerated. We advise that you use a secure method of storage.
2. On Zapier, access the developer platform at https://developer.zapier.com/. Click "Start a Zapier Integration". Note that the app status is Private which means that only you will be able to use it in a Zap.
Fill in the form and click "Create". An RKVST thumbnail image is attached to this article which you can upload to use as a logo.
3. Click on Authentication, select "Session Auth" and then "Save".
4. Configure the fields that will allow the user to enter their client ID and secret. Select "Save & Continue"
5. Configure the REST API call to request an access token. Configure the headers and request body. Select "Save & Continue".
6. Configure a test API call to verify that the connection works. Select "Save & Continue"
7. Test the authentication. Select "Save & Finish" if the call is successful.
Trigger.
The trigger is quite simple, it involves a GET API call to retrieve a list of assets and Zapier identifies if any new assets exist. You can pair this to a messaging app such as Gmail, Outlook or Slack.
Select "Triggers" and then "Add Trigger".
Settings
Fill in the form for the settings tab. Click "Save and Continue".
Input Designer
No input fields are needed for the trigger.
API Configuration.
This section configures the GET call to be used to find new assets and if a new asset is found the Zap will move onto the action. To achieve this Zapier expects the response to include the key "id" but this key is represented by "identity" in RKVST.
To resolve this issue we need to use the "Code View" interface to directly access the JavaScript that makes the API call and handles the response. This allows us to add code to intercept the response and assign the value of "identity" to "id".
A JavaScript sample is attached to this article for you to use in the Code View (GenericTrigger.js). Select "Save API Request & Continue"
Test the API call to make sure it works. Select the account to use and then select "Test Your Request".
Select "Finish Testing & Continue".
Action
The action will create a new asset in response to a trigger received from an app such as DropBox, Google Drive, or OneDrive.
Select "Actions" and then "Add action".
Settings
Fill in the form for the settings tab. "Save & Continue".
Input Designer
The input designer will be used to define the fields that are required for the JSON payload that is used by the POST API call.
The mandatory fields are "arc_display_name", "arc_display_type". You can provide also provide a choice for the fields "proof_mechanism" and "public" using a dropdown if you wish.
The RKVST JSON keys that can be represented by a field can be found in the output of your Authentication Session Auth test.
You can add additional optional fields providing that a value is included in the Trigger. For example DropBox will include a content hash that you might want to record.
API Configuration
RKVST uses a nested JSON for the API call that creates an asset but the API configuration UI on the Zapier free tier does not support this complexity. This is resolved by using the Code View to build the JSON payload and execute the API call.
A JavaScript sample is attached to this article for you to use in the Code View (GenericAsset.js). Select "Save API Request & Continue"
Test the API call to make sure it works. Select the account to use, fill in the form (this simulates a Trigger event) and then select "Test Your Request".
Select "Finish Testing & Continue".
The App is complete and can be used in a Zap.
Google Drive has an additional trigger.
Unlike DropBox or OneDrive, Google Drive provides an additional Trigger for uploads of new file versions. You can build a second action to take advantage of this which will record the new document version as an event on the original document asset.
The event action will need a way to identify the correct asset to record the event against. In the sample code we have used the field "document_unique_id" for this purpose. You need to ensure that you assign the same value to this field when you set up both the New Asset and New Event Zaps and the New Event Zap relies on the New Asset Zap having been processed first so that the document_unique_id can be found.
This is a possible configuration for Google Drive Assets:
This is a possible configuration for Google Drive Events:
The Javascript samples for these Actions are attached below (GoogleDriveAsset.js and GoogleDriveEvent.js).
Attachments.
These can be pasted into the API Configuration code view and modified to match your Input Designer configuration.