|This content applies solely to Appian Portals, which may require an additional license purchase.|
Every portal needs at least a portal object and a primary interface, but a portal can contain that and so much more. This page walks you through creating a portal, from the very beginning of development through deployment.
Each step in this walk-through will give you a high level overview of what to do for the main action of the section. Some steps are optional and, depending on your use case, you may not need every step for your portal.
Before we dive into creating your primary interface and portal object, we need to set up a service account to allow your users access to any data or document connections they may need.
There are a few ways to create a service account. You can create one while creating an API key or you can create one from scratch. Since most portals will require an API key to use with a web, we'll walk through how to create a service account when creating an API key.
To create a new service account:
If you don't plan on using a web API to write or query data using your portal and you need a new service account, you can create one from scratch by creating a new user and adding the user to the Service Accounts group.
You'll add your service account to your portal object later on. For more information, see Step 4.
Before you deploy a portal to a new environment, deploy any groups used to set permissions for your portal and create a service account with the same name as the service account used for your portal. To learn more, see deploying a portal.
When you create the supporting objects for your portal, grant your service account permission to access your portal by giving it the appropriate permissions and group membership.
Below is general guidance for giving your service account permissions to your objects. Alternatively, you can create new end-user groups with more granular permissions to your application objects.
Generally, to grant access to your portal:
Give the Users group the appropriate permissions below depending on your use case.
It's important to consider not only the data that you want your users to see or submit, but consider where that data lives and the structure of the data.
For most cases to query and write data in a portal, you can connect your portal to Appian data and records using integrations and web APIs.
This section points you to content on how to write to or query from an Appian record type or data source. You'll need to set up a web API, connected system, and integration to connect your portal to Appian.
For writing data in a portal, see Writing data.
For querying data in a portal, see Querying data.
For a checklist of all the objects that you'll need for querying and writing data, see What is a Portal.
For instructions on directly writing or querying data using an external database, see Connecting to external databases in a Portal.
Using documents in your portal is similar to using them in a standard interface or application. This section points you to content on how to upload, download, and view documents in your portal.
For uploading files, see Uploading files in a portal.
For downloading files, see Downloading and viewing files in a portal.
With all of our supporting objects and connections set up, we can now create and configure our portal object and connect everything in just a few steps.
This section will provide a brief overview of the steps to make a fully configured portal object, complete with credentials.
To create a portal object:
Later on, we'll create and add the primary interface to the Content field in Step 6.
With the portal object created, we can now add our service account.
To add your service account:
In the Branding section, you can make changes to any of the default branding configurations to fit your organization's branding guidelines. After we add our primary interface as the content of our portal object, you can preview some of your configurations the Branding Preview.
In the Progressive Web App (PWA) section, you can configure your portal to be a progressive web app. A progressive web app looks and behaves like a native application and allows your users to install the portal on their device for easy and frequent access.
You can add reCAPTCHA to your portal to help you monitor your portals for spam or potentially malicious activity. Using a reCAPTCHA connected system, Appian works with Google’s reCAPTCHA services so that you can help mitigate misuse of your portal.
To create a reCAPTCHA connected system from your portal object:
Enter the Google reCAPTCHA credentials.
|Connected System Field||Google Cloud Name (and Location)*||Description|
|reCAPTCHA Project ID||Project ID
|Project ID for the Google Cloud project. To create a project, see the Google documentation.|
|reCAPTCHA Site Key||Key ID
(Security > reCAPTCHA Enterprise)
|The key ID configured for your portal, also known as the site key. To create a key ID, see the Google documentation.
When creating the key:
- For platform type, choose Website.
- Add your portal's domain to the Domain list.
After you create the key, simply copy it and add it to the connected system. No additional set up is required.
|reCAPTCHA API Key||API Key
(APIs & Services > Credentials)
|Sensitive. An API key with reCAPTCHA Enterprise API enabled. To create a reCAPTCHA Enterprise-enabled API key, see the Google documentation.|
*Information from Google is subject to change.
Now it's time to create primary interface to use as the content of your portal object and the main UI that your users will interact with in your portal.
To create a primary interface through the portal object:
Keep in mind a few guidelines that are specific to the primary interface for your portal:
For a full list of design considerations for your primary interface, see Portal Design Best Practices.
Now that you have your primary interface created, it's time to add the connections you created earlier.
This section provides an overview of the steps to add integrations, document upload and download components, and reCAPTCHA functionality to your primary interface.
After you've created both your data connection objects for querying and writing data and your primary interface, you can call your integration from your primary interface.
For more in-depth instructions for both writing and querying data with a portal, see Working with Data in a portal.
For instructions on writing or querying data using an external database, see Connecting to external databases in a Portal.
To call your integration to write data from an interface:
rule!and the name of your integration inside the saveInto parameter of a component.
For an example of calling your integration for writing data from an interface, see Calling an Integration to Modify Data.
To call your integration to query data from an interface:
rule!and the name of your integration in a local variable or wherever relevant in your expression.
For an example of calling your integration for querying data from an interface, see call your integration. For an example of casting your dictionary results, see the example on Working with Data in a Portal
You can use documents in your portal similarly to using them in a standard interface or application. This section gives you a high-level overview of how to add the connections needed to upload, download, and view documents to the primary interface for your portal.
For more in-depth instructions on using documents in your portal, see Working with Documents in a Portal.
To allow your users to upload files in your portal:
To allow your users to download files and view document images in a portal:
To use your reCAPTCHA connected system in your portal, connect to it in your primary interface using the recaptchaSaveInto parameter and the a!verifyRecaptcha().
To call your reCAPTCHA connected system from an interface:
verifyRecaptchafunction, use the a!save function.
fv!scoreand create conditional logic to define what happens when reCAPTCHA successfully evaluates and returns a score.
verifyRecaptchafunction, use the a!save function.
fv!errorto show the error and define what happens when reCAPTCHA does not successfully evaluate.
With your supporting objects and portal object all created and configured, your portal object is now ready for publishing!
To publish your portal object:
For more information on publishing, see Manage a Portal.
Now that your portal is published, it's time to test it. It's important to test both your individual objects and the published portal as a whole.
Navigate to the published portal using the URL under Web Address and test your portal as a user would interact with it.
To make sure that everything is functioning correctly, fully test all of the objects, connections, and primary interface fields and components that your portal relies on, including the following:
Be sure to fill out all of the fields, whether they are required or not, and go through all of the steps in your portal. If you run into any issues while testing, check out the Visitor Activity Logs in your portal object.
If you found any problems with your portal during testing, go ahead and make changes to your primary interface, supporting objects, portal object, or connections. Once you've made and saved your changes, you must republish your portal to be up-to-date.
To republish your portal:
To learn about who can see your portal during testing, see Manage a Portal.
Once you've created, published, and tested your portal object, it's time to deploy your portal to the next environment. To deploy your portal, just include it in your existing deployment pipeline with an application or in a package.
If you have your environments set up for direct deployment, use Compare and Deploy to get your portal ready for deployment.
When you're ready to deploy, remember to include all of the portal's precedents and an ICF with your API key and connected system credentials. In the new environment, make sure that there's already a service account of the same name as the service account associated with your portal with the correct group membership and permissions.
You're ready to go!
To learn more about deploying your portal, see Manage a Portal.
Congratulations! You created a nice and shiny new portal!
After a successful deployment to your target environment, you can now share your portal with your users at the web address specified in the portal object and celebrate.
Create a Portal