Working with Data in a Portal
This content applies solely to Appian Portals, which may require an additional license purchase.

Overview

For your external users to complete their workflows and tasks with ease, they'll likely need to enter or view data within your portal. Writing and querying data in a portal allows you and your users to easily get and share more information than ever.

There are two ways to write and query data within your portal:

This page will explain how to use the web API and integration method to work with data in your portal.

Writing data

Writing data to your data stores through a portal opens the door to new users and more information. Portal users can fill out a questionnaire, respond to an anonymous survey, request rebates or services, apply for grants, or kick-off their own onboarding process. But while you're reaching more information and a broader audience, you still need for your data to stay safe. Portals' isolated architecture gives you the best of both, by allowing you to write data to your data stores safely and effectively from public forms.

For most use cases, you likely want to connect to an Appian data store, whether your data is stored in Appian or some other database. To write data from your portal to an existing data store in Appian, you'll need to create a web API, an integration, and a few objects to go with them.

For information on writing data in your portal directly to an external database, see Connecting a portal to an external database.

Create your web API

You'll first need to create a web API that writes data directly to your data store. To help you get started with creating your web API, use the Write to Data Store web API template when you go to create a new web API. Included in this template, there is a section of code that casts the result of your integration first to a dictionary and then to the CDT you're using for your data. This casting becomes relevant later on when you're setting up your integration.

If you need help creating a web API that writes to a data store, go through the Web API Tutorial Level II.

Create your API key and connected system to write data

After creating your web API, we recommend that you set up an API key and service account in the Admin Console. Follow the steps for creating an API key, or you can use existing API keys and service accounts. Be aware that you need system administrator permissions in order to create an API key.

You can use the same service account that you set up with your API key as the service account for your portal. For more information, see the Security and service accounts section below.

Now you need to add your API key and credentials to a connected system for the integration. To create a connected system for authentication:

  1. Create a new HTTP connected system.
  2. For Authentication, select API.
  3. For Header, enter Appian-API-Key.
  4. For Value, provide the API key value pair from your API key setup.

Create an integration

Once you've created your API and authentication objects, create an integration that is set up to modify data using the connected system that you just created.

To configure your integration:

  1. On the right side under RULE INPUTS, add the CDT that you're using for your data as a rule input.
  2. In the Connection section, configure the following fields:
    • For URL, enter the web API URL as the endpoint for the integration.
    • For Method, select POST.
  3. In the Request Body section, do the following:
    • For Content Type, select JSON.
    • Call your rule input into the request body of your integration.
  4. In the Automatic Output Parsing section, check Automatically convert CDT, dictionary, or list to JSON. This converts your integration results from the CDT in your rule input into JSON, which will then be converted to a dictionary and back into your CDT when it's called into your web API.

For more help, see Create an Integration.

Call your integration from your portal

Finally, call your integration into the interface used for your portal. For examples on how and where to call your integration in the portal, check out Calling an Integration to Modify Data.

Provide connection information in the import customization file

When you publish the portal in the Portal Publishing Manager, upload an import customization file (ICF) to the Application Properties Data field. In the ICF, provide your API key as well as any other connected system credentials and information. For more information, see How to publish a portal.

Query data

Querying data from your Appian data stores and record types through a portal allows for more of your users to quickly and easily access information. While using your portal, users may need to check out the status of their in-flight processes, view information about your products or services, or search public records. We understand that allowing public access to some of your data may seem risky, but don't worry. Portals' isolated architecture gives you peace of mind while allowing you to query data from your data stores for public access safely and efficiently.

For most use cases, you likely want to connect to an Appian data store, whether your data is stored in Appian or some other backend database. To query data from an existing data store or record type to use in your portal, you'll need to create a web API, an integration, and a few objects to go with them.

For information on querying data in your portal directly from an external database, see Connecting a portal to an external database.

Create your web API

You'll first need to create a web API that queries your data store or record type. To help you get started with creating your web API, choose either the Query Data Store or Query Record Type template when creating a new web API. Using an API template automatically populates some common fields and selections to start you out. Both of these templates give query results formatted in JSON.

For general help creating a web API, check out Creating web APIs. For specific help creating a web API that calls your record type, go through the web API Tutorial.

Create your API key and connected system to query data

After creating your web API, we recommend that you set up an API key and service account in the Admin Console. Follow the steps here for more information or you can use existing API keys and service accounts. Be aware that you need system administrator permissions in order to create an API key.

You can use the same service account that you set up with your API key as the service account for your portal. For more information, see the Security and service accounts for working with data section below.

Now you need to add your API key and credentials to a connected system for the integration. To create a connected system for authentication:

  1. Create a new HTTP connected system.
  2. For Authentication, select API.
  3. For Header, enter Appian-API-Key.
  4. For Value, provide the API key value pair from your API key setup.

Create an integration

Once you've created your API and authentication objects, create an integration that is set up to query data using the connected system that you just created.

Make sure that you have the GET content type and Convert JSON to Appian value response body parsing selected. This casts the JSON query results returned by your web API back to a dictionary.

For general help creating an integration, follow the steps here.

Call the integration from your portal

In the interface used for your portal, call your integration and cast the dictionary results returned by your integration into the CDT that you're using for your data. This will let you easily reference your queried data throughout your portal without extra formatting.

Instead of casting your integration results from a dictionary to a CDT directly within your interface, you have the option to create individual or reusable expression rules to cast your integration results. You would then call the integration from your interface and wrap it in the expression rule.

Example: Cast integration results to CDT in a portal

Using local variables within an interface, you can cast your integration results from a dictionary to whichever CDT you're using to work with your data.

1
2
3
4
5
6
7
8
9
a!localVariables(
  local!data: cast(
    type!myCDT,
    rule!myQueryIntegration().result.body
  ),
  a!gridField(
    data: local!data
  )
)

For further examples, check out calling an integration to query data.

Provide connection information in the import customization file

When you publish the portal in the Portal Publishing Manager, upload an import customization file (ICF) to the Application Properties Data field. In the ICF, provide your API key as well as any other connected system credentials and information. For more information, see How to publish a portal.

Example: query data that was previously submitted in your portal

Your users may need to come back to your portal at different times to access data that they've previously submitted using your portal. They might need to check on the status of their application or filed claim. To give them access to this data, set up a workflow that allows them to enter a value that triggers a query to retrieve their data.

Possible values could include:

  • A unique code.
  • A claim or application number.

You can provide values like a code or number in a variety of ways, here are a couple of ideas:

  • Send it in a follow-up email sent from a process.
  • Show it in the confirmation step of a wizard within your portal.

Be aware that this type of design should not be used to access information that a user would typically have to sign in to a user account to access. This workflow is different from a “sign in” experience and should not designed to imply or be referred to as such. Additionally, keep in mind that certain functionality such as automatic sign-outs or session time-outs are not supported.

Security and service accounts

In order for your portal users to be able to write and query data from your portal using a web API, they need to have permissions to your portal's web API, as well as its data store or record type. Since portal users are external and don't have individual Appian user accounts, grant them Viewer permissions to web APIs and data sources using a service account, an API key, and end-user groups.

To give users access to your data sources:

  1. Create an API key and select a service account to be associated with it. You can use an existing service account or create a new one.
  2. Copy your API key and keep it in a secure place. You can't access the API key again.
  3. Add that same service account to your Users group in your application.
  4. Give the Users group Viewer permissions to your web API, as well as your data store or record type, or create new end-user groups with more granular permissions to your data store, record type, and application objects.
  5. When you create your HTTP connected system, add your API key.
  6. When you publish your portal, add your API key to the import customization file and upload the file to the Application Properties Data field in the Portal Publishing Manager.

For more information on setting up your web API and a service account, see the Create your API key and connected system section above.

For more information about using service accounts with your portal, see Service Accounts in Portals.

Which service accounts need to be added to the Portal Publishing Manager

You can only link one service account to your portal in the Portal Publishing Manager. If you're using both documents and external databases, use the same service account for both. If you have service accounts that are only used with web APIs to write or query data from Appian or other non-public external databases, you don't need to add them in Portal Publishing Manager.

However, be sure to always add your API key to the import customization file and upload the file to the Application Properties Data field in the Portal Publishing Manager when using a web API.

Testing

Be sure to fully test all parts of the connections to your portal with a production-level amount of data and usage to make sure everything is performing at scale. This includes all web APIs, integrations, and connected systems. Test your portal both before and after publishing to make sure your users can write and query data correctly. Some connections can't be tested until after publishing.

Open in Github Built: Mon, Nov 21, 2022 (01:52:20 PM)

On This Page

FEEDBACK