Skip to main content

logoCorrectSize.png

Adaptive Insights LLC.

Create a Custom Cloud Loader

Contains preview content for the upcoming 2019.3 release. 

Thorough JavaScript programming knowledge and experience are required to build a Custom Cloud Loader. You should not begin creating a Custom Cloud Loader if you do not have access to an experienced JavaScript programmer. You must also be assigned the Integration Developer permission within Adaptive Insights Administration > Roles and Permissions before attempting to create a Custom Cloud Loader.

A Custom Cloud Loader lets you export Adaptive Insights plan data directly to third-party cloud systems.

Watch the video: 3m 16s

Custom Cloud Loader
 

Basic Steps

  1. Enter data source settings.
  2. Define paremeters.
  3. Write javaScript using the CCDS APIs.
  4. Define business rules.
  5. Run or schedule the loader.

Before You Begin

  • Verify that you have the Integration Developer role permission.
  • Verify that Adaptive Insights plan data you want to export already exists in a staging table.
  • Create an OAuth credential for your external system, or obtain credentials you can explicitly include in your javaScript.
  • Know what parameters you need to pass to your external system, and what defaults the external system expects.
  • Understand how to write to the external system's endpoint.

How You Get There

Compass.png Go to nav menu navicon.gif > Integration > Design Integrations

Enter Data Source Settings

The Data Source Settings let you choose the source table you want to use from your instance's staging data, determine what credentials to use, and the level of log detail to record during a loader run.

Create a new Custom Cloud Loader

  1. Access the Data Designer by going to Integration > Design Integrations.
  2. In the Loaders folder in the Component Library select Create New Loader.
  3. Select Custom Cloud Loader as the loader type and enter a name. If you don't see Custom Cloud Loader as an option, it is not enabled for this instance or you don't have the Integration Developer role permission needed to access it.
  4. Select Create.

Select the Source Table, Credential, and Log Level

  1. Enter the Custom Cloud Loader's information:
  • Source Table: Select a staging table containing Adaptive Insights planning data you want to export.
  • Require Credential: Select if the external system requires OAuth and you require a user with Integration Operator role permission to select the appropriate OAuth credential.
  • Credential: Select a preexisting OAuth credential. 
  • Log Level: Select how much detail to log when the loader runs:
    • Error: Only logs errors.
    • Info: Logs all basic information, such as when the data source was updated.
    • Verbose: Provides very detailed information about all phases and actions. Used primarily for debugging or auditing, as it may produce more log information than practical for typical use.
  1. Click Save in the actions menu.

Define Parameters

Define what parameters your javaScript requires to export Adaptive Insights data to your external system. Parameters can include connection URLs, user names, passwords, dimensions from Adaptive Insights, and other information. Paremeterized settings let you change their values at run time. Static settings persist across loader runs.

  1. Select Designer Settings.
  2. Drag Parameterized or Static setting items from the Settings Component pane into the canvas under Designer Settings. 
    • Parameterized setting values entered here become loader defaults if you don't provide another one at loader run time.
    • Static settings you enter here get used every time the loader runs and don't require input at run time.
  • Boolean: A value represented as one or zero.
  • Dimension: A dimension from the dimension admin within Adaptive Insights.
  • Integer: A non-negative whole number.
  • Password: A password. This value cannot be viewed once it is saved.
  • Period Range: A time period range from within Adaptive Insights.
  • Text: An alphanumeric value.
  1. Double click an item in the canvas to give the parameter a name and edit it.
  2. Drag in as many items as you need to reference in your javaScript.
  3. Save the loader.
  4. Use a parameter's name in your JavaScript to reference it.

Write JavaScript

  1. Select Script.
  2. Select the preexisting template and edit it or select New Script to make your own.
  3. Write the javaScript you want the loader to execute using the CCDS scripting API.
  4. Verify the script includes the required:
  • testConnection function to create an https request to post to your external system
  • exportData function to export data from Adaptive Insights.
  1. Reference any parameters you created in the Designer Settings by their name.
  2. Save the script.

You can format and beautify a script in the editor using the keyboard shortcut Ctrl+B. Find and replace launches with Ctrl+H.

You can separate a long script into multiple files for easier maintenance. For example, you could contain all of your testConnection logic in one script called testconnectionscript. A second script, called exportdatascript, could contain all of the exportData logic. When the same function is declared in multiple scripts, the one from the most recently added script is used.

Use OAuth in Custom Cloud Loader Scripts

When you select Require Credential for a Custom Cloud Loader, your script must contain ai.https.authorizedRequest.

See Authenticate with OAuth for how to create an OAuth Credential.

Those who run a Custom Cloud Loader referencing a Credential should:

  1. Select Request Authorization before running the loader.
  2. Provide any additional authorization details, such as scope, needed for the external system endpoint.
  3. Select Test Connection to verify the OAuth credentials passed successfully to the endpoint.
  4. Note the authorization date and user ID in the Authorization Status. Authorization expiration dates vary from one external system to another. Select Reset Authorization in the Actions pane to reauthorize when needed.

Define Business Rules

You can use Business Rules to create SQL expressions that limit the staging data that exports to the external system. Only records that meet your filter criteria will load.

The Business Rules tab contains a text area for entering SQL.

  1. Select the Business Rules tab.
  2. Select Edit.
  3. Enter an SQL expression. You can click an item in Available Columns to bring that column into the SQL expression instead of typing it.
  4. Select Apply to check your syntax. Errors turn the border around the expression red. Hover the expression to see syntax error information.
  5. Correct any errors in your syntax and select Apply. Only staging rows that match the SQL expression will load.

Include the Custom Cloud Loader in an Integration Task

Custom cloud loaders must be run as integration tasks. Any Integration task can contain one or more loaders. A task can also contain other integration tasks and loaders.

Best Practice: Have separate Integration tasks for each loader.

If a task contains multiple loaders, then parameters from each loader are presented when the task is run. If there is a common/shared parameter used in the loader(s) within a task, then the task only prompts for the parameter once. You can choose to override parameter prompts. 

For scheduled runs of the task, the default values of the parameters stored when the loaders were created are used.

  • Was this article helpful?