Develop Your First Connected System

Overview

Copy link to clipboard

This page provides a follow-up to developer setup. This page details how to create a project, build it, and deploy it to your Appian site, all in about 30 minutes.

Create a unique project from the Hello World example

Copy link to clipboard

This section guides you through the process of creating a new IntelliJ project from our examples. You can refer back to this section whenever you are creating a new project from one of these examples.

Download and set up the examples

Copy link to clipboard

1. Clone the integration SDK example repo in a location of your choice.
2. Navigate to integration-sdk-examples/Connected System Plug-in (CSP) Examples.
3. Rename the Hello World folder to Hello Appian.

Update project-specific IntelliJ and Gradle settings

Copy link to clipboard

1. Open IntelliJ.
2. Open the folder you renamed in step 1 (Hello Appian):
   1. Select File > Open.
   2. Navigate to and select the Hello Appian folder.
   3. Click Open.
3. If additional dialogs appear, select gradle, and continue through the dialogs using the default values.
4. Open the settings.gradle file.
5. Change the value of rootProject.name from hello-world-csp to hello-appian-csp.
6. Close settings.gradle.

Ensure your project is using Java 17

Copy link to clipboard

1. Select File > Project Structure.
2. Click the Project tab.
3. For Project SDK, select corretto-17. If this version is not an option, see the developer setup instructions.
4. Click OK to close the dialog.
5. Select IntelliJ IDEA > Settings.
6. Select Build, Execution, Deployment > Build Tools > Gradle.
7. For Gradle JVM, select Project SDK.
8. Click OK to close the dialog.
9. Select Build > Build Project and confirm that project builds with the updated settings.

Give plug-in artifacts unique names

Copy link to clipboard

In this section, you will update the packages, classes, and annotations to make your project unique.

• Select View > Tool Windows > Project.

You will see two folders: Hello Appian and External Libraries.

Update packages

Copy link to clipboard

1. In the Project tool window, navigate to src/main/java. You will see there is a package called com.mycorp.helloworld.templates.

   

2. Right-click com.mycorp.helloworld.templates and select Refactor > Rename.
3. Click All Directories.
4. In the Rename field, change mycorp.helloworld to example.helloappian.

5. Click Refactor.

   

6. Delete the now-empty helloworld directory.

Update template classes

Copy link to clipboard

The com.example.helloappian.templates package contains two Java classes: HelloWorldConnectedSystemTemplate and HelloWorldIntegrationTemplate.

1. Update class names:
   1. Right-click HelloWorldConnectedSystemTemplate.
   2. Select Refactor > Rename.
   3. Change the name to HelloAppianCSP.
   4. Select Change in comments and strings.

   5. Click Refactor.

      

   6. If the Refactoring Preview pane appears, click Refactor.
   7. Right-click HelloWorldIntegrationTemplate.
   8. Select Refactor > Rename.
   9. Change the name to HelloAppianIntegrationTemplate.

   10. If the Refactoring Preview pane appears, click Refactor.

       

2. Check the @TemplateId annotations:
   1. In HelloAppianCSP, verify the @TemplateId annotation is name="HelloAppianCSP".
   2. In HelloAppianIntegrationTemplate, verify the @TemplateId annotation is name="HelloAppianIntegrationTemplate".

   TemplateId is the identifier for your template and all its versions. To ensure your ID does not conflict with other templates, we recommend using package-structure-style naming (for example, com.mycorp.template).

3. Ensure @IntegrationTemplateType annotation is correct.

   Integration template type indicates the request policy of your integration template. There are three types: READ, WRITE, and READ_AND_WRITE. READ indicates that the template retrieves data from an external service, WRITE indicates that the template modifies data on an external service (such as HTTP POST or HTTP DELETE). If the template can modify or query data depending on the designer's intent, then annotate the template with READ_AND_WRITE. If a template is READ_AND_WRITE, the designer can indicate which type of operation they intend to perform.

   Since we are not modifying the request type of the HelloWorld template, we will leave the template type as READ.

4. Update the import value in HelloAppianIntegrationTemplate:
   1. Open HelloAppianIntegrationTemplate.
   2. Change the first import from com.mycorp.helloworld.templates.HelloWorldConnectedSystemTemplate.CS_PROP_KEY to com.example.helloappian.templates.HelloAppianCSP.CS_PROP_KEY

After modifying the configuration of your classes, the class structure should match the following code.

1
2
@TemplateId(name="HelloAppianCSP")
public class HelloAppianCSP extends SimpleConnectedSystemTemplate {...
Copy

1
2
3
@TemplateId(name="HelloAppianIntegrationTemplate")
@IntegrationTemplateType(IntegrationTemplateRequestPolicy.READ)
public class HelloAppianIntegrationTemplate extends SimpleIntegrationTemplate {...
Copy

Update the Appian Plug-in XML

Copy link to clipboard

1. Open src/main/resources/appian-plugin.xml.
2. Change the <appian-plugin> element's name from My Corp Connected System - Hello World to My Corp Connected System - Hello Appian, and change the key from com.mycorp.helloworld to com.mycorp.helloappian.
3. Change the <description> to fit your template's description.
4. Update the <connected-system-template> element's attributes:
   • key: HelloAppianConnectedSystem
   • name: HelloAppianConnectedSystem
   • class: com.example.helloappian.templates.HelloAppianCSP
5. Update the <integration-template> element's attributes:
   • key: HelloAppianIntegrationTemplate
   • name: HelloAppianIntegrationTemplate
   • class: com.example.helloappian.templates.HelloAppianIntegrationTemplate

This information should now look like the code below:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<appian-plugin name="My Corp - Hello Appian" key="hello-appian">
    <plugin-info>
        <description>My Corp Connected System - Hello Appian</description>
        <vendor name="Example Corp" url="http://www.example.com"/>
        <version>1.0.0.0</version>
        <application-version min="7.6.0.4"/>
    </plugin-info>
    <connected-system-template key="HelloAppianConnectedSystem"
            name="HelloAppianConnectedSystem"
            class="com.example.helloappian.templates.HelloAppianCSP">
        <integration-template key="HelloAppianIntegrationTemplate"
                name="HelloAppianIntegrationTemplate"
                class="com.example.helloappian.templates.HelloAppianIntegrationTemplate" />
    </connected-system-template>
</appian-plugin>
Copy

Update template name and description

Copy link to clipboard

1. Open src/main/resources_en_US.properties.
2. Change the resource keys to match the class names:
   • Change HelloWorldConnectedSystemTemplate to HelloAppianCSP.
   • Change HelloWorldIntegrationTemplate to HelloWorldIntegrationTemplate.

This resource file should look like the code below:

1
2
3
4
5
## Must have [class].name and [class].description for all connected system and integration templates
HelloAppianCSP.name=Hello Appian Connected System
HelloAppianCSP.description=Sample CS for learning how to use plug-in repo CSPs!
HelloAppianIntegrationTemplate.name=Hello Appian Integration
HelloAppianIntegrationTemplate.description=Sample CS for learning how to use plug-in repo CSPs!
Copy

Now that all of the configurations meet your template's requirements, the Connected System Template and Integration Template can be modified with the logic needed for your integration.

Build and deploy the JAR

Copy link to clipboard

Now that you're done updating your template code and artifacts, you're ready to build and deploy the JAR.

To create the JAR from the command line:

1. Navigate to your project's root directory.
2. Run the following command: ./gradlew jar.

To create the JAR from IntelliJ:

1. From the menu bar, select View > Tool Windows > Gradle.

2. In the Gradle projects pane, select Tasks > Build.

   

3. Double-click the jar job.

If everything is set up correctly, you will see a success message in the console and a JAR file will be created in /build/libs.

To deploy the JAR, add the file to the <APPIAN_HOME>/_admin/plugins folder.

How to check if the CSP deployed successfully

Copy link to clipboard

Look at the connected system in Appian Designer

Copy link to clipboard

1. Open your browser and navigate to <Appian.instance>/design.
2. Click New > Connected System and in the modal your new connected system type should appear.

Look at the plug-in list in the Admin Console

Copy link to clipboard

1. Open your browser and navigate to <Appian.instance>/admin.
2. From the SYSTEM menu, go to plug-ins. The plug-in will appear in the Deployed plug-ins list.

Look at the logs

Copy link to clipboard

On Tomcat, go to <APPIAN_HOME>/logs. Then run:

1
tail -f tomcat-stdOut.log.<date>
Copy

You're looking for the following messages:

Connected System Template

1
[Appian Plugin Hot Deploy] INFO  com.appiancorp.connectedsystems.templateframework.osgi.ConnectedSystemTemplateModuleParser - Extracted com.appiancorp.connectedsystems.templateframework.sdk.ConnectedSystemTemplate classes for registration for the 'HelloAppianConnectedSystem' module in 0ms
Copy

Integration Template

1
[Appian Plugin Hot Deploy] INFO  com.appiancorp.connectedsystems.templateframework.osgi.ConnectedSystemTemplateModuleParser - Extracted com.appiancorp.connectedsystems.templateframework.sdk.IntegrationTemplate classes for registration for the 'HelloAppianConnectedSystem' module in 0ms
Copy

Plug-in successfully installed

1
[Appian Plugin Hot Deploy] INFO  com.appiancorp.plugins.osgi.AppianOsgiPlugin - Successfully installed Plug-in 'My Corp Connected System - Hello Appian (hello-appian) version 1.0.0.0.
Copy

Congratulations! Your plug-in should now be deployed. Follow the steps below to test it out.

1. Open an application in the Appian Designer.
2. Click New > Connected System.
3. In the Custom (BETA) category, choose your new template.
4. In the Connected System designer, enter a name.
5. Enter Hello in the Text Property field.
6. Click Use in New Integration.
7. Enter a name.
8. Click Create.
9. From the Integration Designer, enter Appian in the Text Property field.
10. Click Test Request.

Your two text properties should be concatenated and Hello Appian should display in the Results pane.

Next steps

Copy link to clipboard

Now you're ready develop your own Connected System Plug-in. You can start by reading through the Core Concepts section to learn important concepts about the SDK, or you can jump straight to the Examples, and go back to the over when you want to get a deeper understanding of what's going on.

At any point, if you need help doing something in particular, check the How To section.

Feedback

Copy link to clipboard