Platform Application Tutorial

Overview

An application is a wrapper around a group of objects, menus, and portals that work together to fulfill a function. You create a Platform application using the Sage Intacct UI.

Using Platform Services, you can create your own applications to efficiently handle unique processes for your company or other companies.

This tutorial shows you how to create a sample application that manages the attendees and presenters for company conferences. You will create custom data objects and then create menus, forms, pages, and workflows for those objects. After completing the tutorial, you will have a good understanding of the capabilities of Platform Services.

Application functionality

The sample application will track attendees and presenters for a company conference.

The end user for the application will be able to:

The application will have some automations:

The following shows the relationships between the application objects. Custom objects are prefaced by the MCA namespace, and the standard object is shown in green.

Hierarchy of application objects

Building the application

Here’s an overview of how we will build the application:

Important: You should not modify a sample application to build a production solution. Always build production applications from scratch in a clean development company without other custom applications and customizations. This ensures you only include what you intend in your application. Also, elements of an application are tied to the company where they were developed through ID numbers. It is better to create your objects in your own development company so you have consistent ID numbers.

Use Action UI for Platform

This tutorial uses the Action UI for Platform Services. You can enable this as follows:

  1. From the upper right, click on your user name, then select My preferences.

    User preference menu

  2. Go to Personalize Platform and Customization Services, choose Action UI as the Layout type, then click Save.

    User preference menu

Create the application wrapper

Let’s create the basic wrapper for the application. We will use a namespace to avoid potential name collisions with other third-party applications or Sage Intacct.

  1. Go to Platform Services > Platform tools > + Applications.

  2. On the Application Properties page that appears, leave This application is deployed checked.

    This makes the application visible to end users, which lets us see the application menus and pages and test the functionality as we go.

  3. Enter MCA My Conferencing App for the Application Name.

    End users will use this menu name to access the application. MCA is the namespace (short for My Conferencing App).

  4. Click Save.

    Your application is now listed under Custom Applications:

    List of applications

  5. Click MCA My Conferencing App to open the Application Definition page.

    The Application Definition page is where you do much of your work. It lets you create custom objects, menus, portals (only available in US locales), and so forth.

  6. Click Edit Properties to look at the application properties.

    There are sections for adding Custom Objects and Standard Objects to your application as well as other properties.

  7. Click Cancel.

Create the custom objects

Now that we have the wrapper for our application, let’s add the three custom objects:

Attendee object

Let’s create the definition of the attendee object. We’ll use the best practice of providing a namespace for the object and tracking any changes for the audit log.

  1. From the Application Definition page, click Objects in the banner:

    Banner menu with objects highlighted

    If you need to get back to the Application Definition page, go to Platform Services > Platform tools > Applications and click MCA My Conferencing App.

  2. Click New Object next Selected Objects.

    Choose application

  3. On the Object Properties & Attributes page that appears, leave the Status Options unchecked.

  4. Enter Attendee as the Singular Name for the object.

  5. Click outside the field and note that the other name fields are autofilled.

    name fields

  6. Change the Integration Name to MCA_attendee.

    Using the namespace is important for avoiding name collisions with other objects.

  7. Under Optional Object Properties, select Audit Trail so there will be a history of when records of this type are created.

  8. Further down, note that Create a new menu for this object and MCA My Conferencing App are checked, then click Save.

  9. In the New Menu page that appears, note that MCA My Conferencing App is checked and click Save.

    You are directed to a page that lists all Platform Services objects.

  10. Scroll down and locate the new object. The ID number for your object will likely be different.

    lister with Attendee object

Conference level object

Let’s use a slightly different approach to create the next object. We’ll create the object first, then add it to the application afterwards.

  1. Go to Platform Services > + Objects.

  2. Enter Conference Level as the Singular Name for the object.

  3. Change the Integration Name to MCA_conference_level.

  4. Check the Audit Trail property.

  5. Under Add to Applications, click MCA My Conferencing App, then click Save.

  6. In the New Menu page that appears, click MCA My Conferencing App under Add to Applications and click Save.

Presenter object

We want the presenter to be able to log into a web page and upload their presentation to the system. There is a property that we can use to accomplish this.

  1. Go to Platform Services > + Objects.

  2. Enter Presenter as the Singular Name for the object.

  3. Change the Integration Name to MCA_presenter.

  4. Check the Audit Trail attribute.

  5. Check the Portal Visitor attribute (only available in US locales).

    This automatically adds login and password fields to the object.

  6. Under Add to Applications, click MCA My Conferencing App, then click Save.

  7. In the New Menu page that appears, click MCA My Conferencing App under Add to Applications and click Save.

About the application

Let’s confirm that the application is now available in the menus:

  1. Reload your browser page.

  2. Go to the Applications menu and choose MCA My Conference App to see the new menus:

    Attendee menu under MCA My Conference App menu

As you continue to work on the application, you will access it in different ways. You can work from the Platform Service menus, like Platform Services > Objects or Platform Services > Platform tools > Applications. You can also access the definitions and properties for your custom objects from the end-user menus we looked at here. More on this later.

Permissions

As the application developer, we can see the application and its menus without setting any permissions. However, other users need permissions for this. How you approach this depends on whether your company has user-based or role-based permissions (see Role-based vs. user-based permissions in the Sage Intacct product help).

This example assumes user-based permissions. If you use role-based permissions, you can add a new role with the permissions and assign that role to a test user.

  1. Locate or create a test user that you can log in as.

  2. Go to Company > Admin > Users, then click on Subscriptions to the right of the user you want.

  3. On the subscriptions page, click the checkbox for My Conference Application (near the bottom of the page).

  4. On the same page, click Permissions to the right of My Conference Application

  5. In the Permissions dialog that appears, grant the following permissions:

    Choose application

  6. Click Save in the Permissions dialog, then click Save on the Subscriptions page.

  7. (Optional) Log in as the test user and verify that you can see the application.

Tip: Be aware that when creating production applications for clients, you need to provide information about how end users set up their permissions for using the application.

Add fields to the objects

Now that we have our three objects, let’s create fields on the objects to provide the functionality we want.

Tip: Because we used namespaces for our custom objects, we are already protected from name collisions on fields—there is no need to use namespaces. However, keep in mind that when you add custom fields to standard objects, you should use namespaces.

Attendee fields

Recall that we need to add the following:

Create the Attendee name field

  1. Go to Platform Services > Platform tools > Applications and click on MCA My Conference App.

  2. In the shortcuts banner of the Application Definition page that appears, click Objects .

    banner with menus

  3. Under Selected Objects, click Attendee. (Click on Attendee, not Edit.)

    This opens the Object Definition page.

  4. Click Fields in the Component List Shortcuts banner.

    Note that our object already has fields that were automatically added, such as Attendee, Comments, Created At, and so forth.

  5. Click New Field at the top of the list.

  6. Click Text for the type and click Next.

  7. Enter Attendee name as the field label.

  8. Check This field is required in all forms and click Save.

    checkbox for option

  9. The Add to Pages and Views screen shows various pages (automatically provided by the system) so that end users can create attendees, edit, import, and so forth.

  10. Click All Attendees under Views, then click Save.

    checkbox for all attendees

Create the Email field

Let’s use a different approach to access the object definition this time.

  1. From the main menus, go to MCA My Conferencing App > Attendees > Attendees.

  2. Click Object Definition in the upper right of the lister page.

  3. Click Fields in the Component List Shortcuts banner.

  4. Click New Field at the top of the list.

  5. Click Email for the type and click Next.

  6. Enter Email as the field label.

  7. Check This field is required in all forms and click Save.

  8. In the Add to Pages and Views screen that appears, click Save to accept the defaults.

Create the relationship to customers

Now let’s add a relationship between our attendee object and the standard customer object so that attendees can be associated with existing customers.

  1. From the Object Definition page for Attendee, click Relationships in the Component List Shortcuts banner.

  2. Click New Relationship next to Relationships.

  3. For the Related Object, click Customer [CUSTOMER], then click Next.

  4. Leave the Singular and Plural Names as is.

    Tip: Note that integration name for the relationship is not autofilled. You should provide an integration name with your relationships or the system will auto generate a name that is not intuitive.

  5. Enter R_attendee_customer as the integration name.

    We use R_ to identify the integration name as a relationship.

  6. For the Relationship Type, choose Many Attendees to One Customer.

    relationship type menu

    A large company might send several attendees to the conference.

  7. Leave the suggested Integration Names for the Lookup Fields as is (RCUSTOMER and RMCA_attendee).

  8. Click Save.

Create the relationship to conference levels

Now lets add a relationship between MCA_attendee and MCA_conference_level

  1. In the Object Definition page for Attendees, locate the Relationships section and click New Relationship.

  2. For the Related Object, click Conference level [MCA_conference_level], then click Next.

  3. Leave the Singular and Plural Names as is.

  4. Enter R_attendee_conference_level as the Integration Name.

  5. For the Relationship Type, choose Many Attendees to One Conference Level.

    Multiple attendees will register at the same conference level.

  6. Leave the suggested Integration Names for the Lookup Fields as is (RMCA_conference_level and RMCA_attendee).

  7. Click Save.

Unique record name

It’s recommended that you use unique names for record names, so let’s do that here:

  1. From the Object Definition page for Attendee, click Edit Properties & Attributes.

  2. In the Available Merge Fields section, select Attendee name from the drop down.

  3. Copy the merge token that displays and paste it into the Record Name Template field.

  4. Use Available Merge Fields again and select ID.

  5. Copy the merge token and paste it into the Record Name Template field. Add two dashes between the tokens, as shown:

    Choose application

  6. Click Save.

View the UI for creating new attendees

Let’s take a look at how users will apply these relationships now that we’ve laid the groundwork.

  1. From the main menu, go to MCA My Conferencing App > Attendees > + Attendees.

    fields for creating new object

  2. Note that the Attendee field, which is the record name, is read only.

    This is because the record name will be automatically generated using the record name template we provided.

  3. Two of the fields are text entry, and the related Customer and Conference level can be chosen with lookups.

  4. Click the magnifying glass next to Customer to show the form for choosing the related customer.

  5. Close the Select Customer form, then click Cancel on the New Attendee page.

Conference level fields

Recall that we need to add the following:

Create the Price Level and Price fields

  1. Open the Object Definition page for Conference Level.

  2. Go to the Fields section and add the following two new fields.

    Field Type Field Label Field is required in all forms Add to Pages and Views
    Text Price level True Accept default values
    Currency Price True Accept default values

  3. Check This field is required in all forms and click Save.

  4. (Optional) From the Object Definition page, click Edit Properties & Attributes and set up a unique record name template like this:

    {!price_level!}--{!id!}

    See the instructions for the attendee object if you need help.

Presenter fields

Recall that we need to add the following:

Because the Presenter object was defined as a Portal Visitor at create time, the following fields are automatically available to use:

Create the fields

  1. Open the object definition page for Presenter.

  2. Scroll down to Fields and click New Field.

  3. Go to the Fields section and add the following new fields—note that there are some options for these fields that we haven’t used yet, such as default value and file extension.

    Field Type Field Label Field is required in all forms Add to Pages and Views
    Text Presenter name True Accept default values
    Field Type Field Label Default Value Add to Pages and Views
    Check Box Active Checked Accept default values

    Note: All custom objects have an isActive field that can be used for the same purpose as the Active field we are adding.

    Field Type Field Label Field is required in all forms Add to Pages and Views
    Email Email True Accept default values
    Field Type Field Label File Extensions Add to Pages and Views
    File Upload Presentation .pdf Accept default values

  4. (Optional) From the Object Definition page, click Edit Properties & Attributes and set up a unique record name template like this:

    {!presenter_name!}--{!id!}

    See the instructions for the attendee object if you need help.

Extra credit - Create a relationship to customers

A presenter could certainly be a customer as well.

Using the steps above as a guide, create a comparable relationship from presenters to customers—use R_presenter_customer as the integration name for the relationship.

View the UI for creating new presenters

Let’s look at how users will create a new presenter:

  1. Go to the main menu and go to MCA My Conferencing App > Presenters > + Presenters.

    Notice that the Login name and Password fields are not present.

    new presenter page

    This is because these two fields are automatically added to an object created as a Portal Visitor, but they are intended for use in a web page that presenters can use for uploading presentations. We are also going to add them to the page for creating a portal user though so we can assign them at creation time.

    Important: Remember that this is a sample application not intended to be used in production. Providing portal visitor passwords must include extra security in production environments.

Add login and password fields to the New Presenter page

  1. Still on the New Presenter page, click Edit this page on the upper right.

    button for page editor

    The Page Editor provides building blocks for the page on the left and the layout space for the page on the right.

    page editor for new presenter page

  2. Drag Login Name from Available Components to directly below Email on the right.

  3. Drag Password to directly below Login Name.

    This component automatically provides two text entry fields so the password can be verified when it is created.

    Login name and two password fields in page editor area under Email field

  4. If you completed the extra credit and have a relationship to the customer object, drag the Customer field below the password fields.

    The page should look like this:

    new presenter page

  5. Click Save.

  6. Go to the main menu and go to MCA My Conferencing App > Presenters > + Presenters again and verify that the two fields are present.

We’ll look at how to provide the login and password to the presenter via an email later.

The three objects for our application are now complete.

Create the portal and pages

We need to create a portal and some pages so that presenters can log in and upload their presentations. We also need a way to provide presenters with their login credentials.

Create a portal for external users (presenters)

  1. Go to Platform Services > Platform tools > Applications > MCA My Conferencing App.

  2. Scroll to Selected Portals and click New Portal.

  3. Enter Conference portal for the Portal Name and for the Sub-Domain Name.

  4. Select Is Deployed and click Save.

Create a login page for presenters

  1. Still on the Application Definition page, click Conference portal under Selected Portals to open the Portal Definition page.

  2. Click New Page in the Pages section.

  3. On the New Portal Page, enter Presenter Login for the Page Name.

  4. For the Page Type, click Login Form.

  5. Choose Presenter for the Object Type, then click Save.

    The Page Editor shows a page with login name and password:

    Page editor for creating upload page

  6. Click Save.

    We now have a login page, but we need to modify the portal so that this page is the first page presenters see.

  7. Go to Platform Services > Platform Tools > Portals and click Conference portal.

  8. Click Edit Properties.

  9. For Main Page, choose Presenter Login and click Save.

  10. Note the Main Page URL link, similar to the example below.

    portal URL

    This link lets external users access the login page.

Create a page for uploading presentations

  1. Still on the Portal Definition page, click New Page.

  2. On the New Portal Page, enter Upload Presentation (.pdf) for the Page Name.

  3. Click Only logged in portal visitors can access this page.

  4. For the Page Type, click Object Edit Page, then select Presenter as the Object Type.

    The Object Edit Page type lets users modify an object, such as by uploading a presentation for a given presenter.

  5. Click Save to display the page editor.

  6. Drag (File Upload) Presentation from the left to directly below the Notification Message box.

  7. Drag a New HTML Component from the left to directly above the logout link on the right.

  8. Click Edit on the new component and add text like this:

    Page editor for creating upload page

  9. Click Save.

Now we need to create a link from the login page to the file upload page.

  1. Click Edit next to the Presenter Login page.

  2. Click the Login Form box on the right to select it.

    Login form box selected

    The Properties on the upper left change to display a Destination Page field.

  3. Choose Upload Presentation (.pdf), then click Save.

    Presenters will now be taken to the upload page after logging into the portal.

  4. Click Save.

Automatically send email

Now that the portal pages are done, we need the ability to send presenters their login information.

We’ll create a trigger to send the email.

Create the Email Trigger

  1. Still on the Presenter object definition, click Triggers in the Component List Shortcuts banner, then click New Trigger.

  2. Set up the trigger:

    • For the Trigger Type, select Send Email and click Next.

    • Select This trigger is deployed.

    • Under Trigger Activation, choose After Create.

      After creating a new presenter, the trigger will execute.

    • Enter Presenter_Welcome as the Trigger Name.

  3. Under Trigger Type Properties, choose Email as the Use Field option.

    Note that Send To is filled in with: {!email!}

  4. For Reply To, enter something like this: noreply@nomail.com

  5. Click the plus sign to the right of Email Template to add a new template.

  6. Provide Presenter Welcome as the Template Name.

  7. Enter Thank you for being a presenter! in the Subject field.

  8. Use a merge field to to include the name of the presenter in the email:

    • Under Available Merge Fields, choose Presenter, then choose Presenter name under the Select Field.

      Note that the merge field shows this token: {!MCA_presenter.presenter_name!}

    • Copy the the token, paste it into the text editor area, and preface it with a greeting:

      Hello {!MCA_presenter.presenter_name!} --

      This will look something like this in the sent email:

      Hello Jen Jones --

  9. Provide the presenter with the URL for the login page:

    • Under Available Merge Fields, choose Conference portal, then choose Presenter Login [link].

    • Copy the token and create a sentence like this:

      Please log in to verify your credentials and upload your presentation: {!#PORTAL.162314@10004.162314@12547#link!}

  10. Use merge fields to provide presenters with their login credentials:

    • Select Presenter as the merge field, choose Login Name, copy the merge field token, and paste it on a separate line at the bottom of the text editor area.

    • Do the same for Password.

    • Arrange text around the tokens as follows:

      Login ID: {!MCA_presenter.loginName!}
Password: {!MCA_presenter.password!}

  11. Add a salutation at the end.

    The complete message should look something like this:

    Completed email template

  12. Click Save at the bottom of the Email Template page, then click Save on the Trigger page.

Provide permission to access portal pages to the presenter

When you first create a portal, the system automatically creates a portal user identity. We need to make sure this user has the appropriate permissions to upload a presentation. In effect, the Portal User will modify a Presenter record in the system by adding a document to it.

  1. Go to Company > Admin > Users, roles, & groups > External users and click Subscriptions in the Portal User row.

  2. Scroll down, go to MCA My Conferencing App, and click Permissions.

  3. Under Objects, click Edit for the Presenter object.

    Page letting presenters log into the portal

  4. Click Save, then click Save again on the Company subscriptions page.

Test the email trigger

Let’s test things by creating a fictitious presenter.

  1. Go to MCA My Conferencing App > Presenters > + Presenters.

  2. Create a presenter, making sure to supply your own email address, for example:

      Presenter name: Jen Jones
  Active: checked
  Customer: 
  Email: your email address
  Login Name: tester
  Password: Welcome123_!

  3. Save the presenter, then check your email and open the message from noreply@nomail.com.

  4. Click the Presenter Login link and use your login ID and password to log in.

    Page letting presenters log into the portal

  5. On the upload page, click Choose File, select a test pdf file to upload, then click Submit.

  6. Log out the user.

  7. Go to MCA My Conference App > Presenters > Presenters to show the list of all presenters. Note the Presenter name, which is based on the record name template we used when defining the new presenter object.

    application presenter name in list view

  8. Click on Jen Jones–xxxxx to view the presenter information:

    presenter information page

Create seed records

It might be helpful to create seed records for the conference price levels. This way, users can modify these records to suit their needs instead of creating them from scratch.

We’ll create three price level records, each with a different price:

  1. Go to the main menu and go to MCA My Conferencing App > Conference Level > + Conference Level.

  2. On the page that appears, enter the following:

     Price Level: Introductory
 Price: 1000

  3. Click Save.

  4. Repeat this for two more levels:

     Price Level: Standard
 Price: 1500

     Price Level: Premier
 Price: 2500

Now that we have our three levels, let’s add them to the application:

  1. Go to Platform Services > Platform tools > Applications, then click MCA My Conferencing App.

  2. Click Seed Records in the Component List Shortcuts banner, then click Attach Record.

  3. In the dialog that appears, choose Conference Level from the dropdown.

  4. Click on Premier, and note that the Application Definition page shows that the seed record was added in a banner message.

    Page letting presenters log into the portal

  5. Click on the other two conference levels to add them, then click Close Window in the Attach Record dialog.

Let’s verify that the seed records are now available in the application:

  1. Go to MCA My Conferencing App > Conference Levels > Conference Levels to open the list view:

    Page letting presenters log into the portal

Automatically create a statistical journal entry

API triggers provide a powerful mechanism for automating tasks.

Let’s assume we want to use an API trigger to keep a running tally of the number of conference registrations. Statistical journals are great for this purpose. A statistical journal entry simply increases or decreases a value—we can automatically create a statistical journal entry each time a new attendee is created.

Before we can create a statistical journal entry, we need to create a simple statistical account and a statistical journal we can use.

Create the statistical account

  1. Go to General Ledger > All > + Statistical account.

  2. Provide the following values, then slick Save.

    Label Value
    Account number ATTD
    Title Conference attendance
    Report type Cumulative balance
    Status Active

Create the statistical journal

  1. Go to General Ledger > Setup > + Statistical.

  2. Provide the following values, then slick Save.

    Label Value
    Symbol MCA-01
    Title Conference attendance
    Status Active

Now we are ready to work on the function.

Create the API Trigger

Here’s an example of a function that creates a statistical journal entry:

<create>
  <GLBATCH>
    <JOURNAL>MCA-01</JOURNAL>
    <BATCH_DATE>12/12/2019</BATCH_DATE>
    <BATCH_TITLE>Conference registration</BATCH_TITLE>
    <ENTRIES>
      <GLENTRY>
        <ACCOUNTNO>ATTD</ACCOUNTNO>
        <TR_TYPE>1</TR_TYPE>
        <AMOUNT>1</AMOUNT>
        <DESCRIPTION>Registration for Jen Jones for $1000</DESCRIPTION>
      </GLENTRY>
    </ENTRIES>
  </GLBATCH>
</create>

Note: If you are using a multi-entity company, you need to include <LOCATION>myLocationID</LOCATION> for the GLENTRY in the XML (see Create Journal Entry for details).

Because we are working inside Platform Services, we don’t need to include any of the header or footer information that is required for an XML request coming in from Web Services.

Let’s create a trigger that executes the function, which is stored as a document template.

  1. On the Attendee object definition page banner, click Triggers, then click New Trigger.

  2. Set up the trigger:

    • For the Trigger Type, choose Intacct API and click Next.

    • Select This trigger is deployed.

    • For Trigger Activation, click After Create.

    • For Trigger Name, enter Create_Stat_Journal.

  3. Under Trigger Type Properties, click the plus sign to add a new document template.

  4. Enter Create registration stat journal as the Template Name.

  5. Copy the create example above and paste it into the code editor area.

  6. Use a merge field to include the name of the attendee in the description:

    • From the Available Merge Fields, choose Attendee as the field type and Attendee name for the field. The token displays: {!MCA_attendee.attendee_name!}

    • Copy and paste the token over the name in the Description element of the API function.

      copy merge field in UI

  7. Use a merge field to include the conference price in the description:

    • From the Available Merge Fields, choose Related Conference level as the field type and Price for the field. The token displays: {!R_attendee_conference_level.price!}

    • Copy and paste the token over the price in the Description element of the API function.

      copy merge field in UI

  8. (Optional) Preview the document template with the merge fields filled in for a given attendee:

    • Click Preview Template.

    • In the Attendees Selector table, click on an attendee name to open the Preview.

      preview merge field window

      (If you don’t yet have an attendee record, there won’t be a name to choose.)

    • Close the Preview template window.

  9. Click Save in the Create Template window.

  10. Scroll to the bottom of the New Trigger page and click Save.

Test the trigger

  1. Choose MCA My Conferencing App > Attendees > + Attendee to create a new attendee.

  2. Go to General Ledger > Setup > Statistical and click View Transactions for the Conference attendance journal.

  3. Click on view for the transaction. You should see something like this:

    journal entry in UI

Troubleshooting

If you don’t see an entry, it probably means there is an issue with the API call. Here are some troubleshooting suggestions.

More extra credit?

If you want a challenge, consider completing the section on creating a sales order with an API trigger. Otherwise, you can skip the challenge and go onto exporting your application’s XML below.

Export the application XML

The application is now complete. Let’s export the application’s XML, which is then available for installation into a target company.

  1. Go to Platform Services > Platform tools > Applications > MCA My Conferencing App.

  2. In the upper right, click Publish.

    UI publish button

  3. In the page that appears, note that the application name and version are filled in for you.

    UI generate xml button

  4. Also note that isManaged is not checked – this is only a sample application, so that’s fine.

    Important: For a production application, the best choice is almost always a managed application. When an application is managed, it cannot be modified after it is installed. If you leave an application un-managed, users can make changes on the installed version, which makes it impossible to update without potential data loss.

  5. Click Generate XML to download the application’s XML definition.

    Important: You should never edit an application’s XML file.

The application can now be installed in a different company. Congratulations on creating your first Platform application!

If you want to install the application on a different development company, see Custom applications in the Sage Intacct product help.

Delete or undeploy an application

If you want to remove the sample application, you have two options:

Undeploy the application

  1. Go to Platform Services > Platform tools > Applications.

    A list of all applications appears.

  2. Next to MCA My Conferencing App, click Edit.

  3. On the Application Definition page, click Edit Properties.

  4. On the Application Properties page, clear the This application is deployed checkbox, and click Save.

Delete the application

Before an application can be deleted, it must be undeployed for a period of time so that the system can update the status in the cache.

  1. Undeploy the application as described above and wait a few minutes.

  2. Go to Platform Services > Platform tools > Applications.

    A list of all applications appears. If the application has been undeployed for long enough, it will look like this:

    lister showing sample app ready for deletion

  3. Next to MCA My Conferencing App, click Del, then confirm the action by clicking the checkbox and Delete.

Challenge: Add an API trigger to create a sales order

We can create a trigger that uses an API function to create a sales order for each new attendee. Your company must have subscriptions to Order Entry and Inventory Control to create a sales order. You must also have a mechanism for sending XML API calls via Web Services.

Note: If you don’t have these subscriptions, you can read through the steps to get an idea of how to create a transaction using an API trigger.

We will use the create_sotransaction function, which will look something like this:

<create_sotransaction>
	<transactiontype>Sales Order</transactiontype>
	<datecreated>
		<year>2019</year>
		<month>3</month>
		<day>27</day>
	</datecreated>
	<customerid>CUST-198</customerid>
	<referenceno>Test</referenceno>
	<datedue>
		<year>2019</year>
		<month>4</month>
		<day>27</day>
	</datedue>
	<message>Jen Jones -- Thank you for registering for the conference!</message>
	<state>Pending</state>
	<sotransitems>
		<sotransitem>
			<itemid>Conference registration</itemid>
			<quantity>1</quantity>
			<unit>Each</unit>
			<price>100</price>
		</sotransitem>
	</sotransitems>
</create_sotransaction>

We are going to use merge fields to grab the needed parameter values. Our attendee object provides these values, but not in the format required.

For example, an attendee record has Created At field with a Date/Time format. However, we need the date broken into year, month, and day for the function call. To address this, we need to add more fields to the object definition.

Create an Inventory Control item for the sales order

We need an item in Inventory Control for the conference level in order to be able to create a sales order. This is just a placeholder item for the purposes of the tutorial.

Note: Creating the conference price levels as Inventory Control items from the start would have worked as an alternative to creating a custom Conference level object. Using a custom object worked well for demonstration purposes for this tutorial.

  1. Go to Inventory Control > All > + Items.

  2. Enter Conference registration for the Item ID and Name.

  3. Choose any available Warehouse ID, then click Save.

Create a test sales order to confirm required fields

Different companies have different requirements for the parameters for create_sotransaction. For example, you will have different customers in your test company, and a multi-entity company requires currency parameters. Before continuing, confirm that you can create a sales order with the API.

Note: The date due for the sales order has to be later than the date created.

  1. Use Postman (or your preferred mechanism) for sending Web Services API functions to your company to verify a working create_sotransaction function. Use the example above as a model.

    If you need help, see Your First XML API Calls.

  2. Save your working function, either in Postman or in a text editor.

  3. Use another XML function call to list attendees:

      <readByQuery>
      <object>MCA_Attendee</object>
      <fields>*</fields>
      <query/>
      <pagesize>100</pagesize>
  </readByQuery>

  4. Note the format for the createdAt value:

    <createdAt>2019-12-13T17:28:49Z</createdAt>

Add Year created field

Let’s use the createdAt field to get the pieces that we need for the create_sotransaction function. Will will add formula fields to the Attendee object to accomplish this.

  1. Open the Attendee object definition and locate the Fields section.

  2. Create a field for accessing only the creation year.

    1. Click New Field at the top of the list.

    2. Click Formula for the type and click Next.

    3. Enter Year created for the field label, and Integer for the Formula Return Type.

    4. Enter the following JavaScript in the formula field. We are using a JavaScript UTC function (getUTCFullYear) so that time zones are handled.

       return new Date("{!MCA_attendee.createdAt!}").getUTCFullYear();

    5. Click check it for errors to validate the formula.

      UI to check formula

    6. Click the magnifying glass, and choose an existing attendee to see exactly what will be returned. The result at the bottom should show just the year.

      validation page showing year returned

    7. Close the dialog, then click Save on the New Field page.

    8. Accept the defaults for the Add to Pages and Views dialog.

Add Month created and Day created fields

Add Due date fields

Now we need to create three comparable fields for the pieces the comprise the date due for the sales order. Let’s use one month past the creation date as the due date.

Note that you could use a net term of 30 to accomplish the same task, but we are working through this exercise as a learning experience.

  1. Create a new Year due formula field on the attendee object that returns an integer type and uses the following formula:

      var d = new Date("{!MCA_attendee.createdAt!}");
  d.setMonth(d.getUTCMonth() + 1); // Add one month
  return d.getUTCFullYear();

  2. Create Month due and Day due fields:

    Field Type Field Label Return Type Formula Pages and Views
    formula Month due Integer return new Date("{!MCA_attendee.createdAt!}").getUTCMonth() + 1; Accept defaults
    formula Day due Integer return new Date("{!MCA_attendee.createdAt!}").getUTCDate(); Accept defaults

Create the API trigger

Now that the Attendee has the fields we need, let’s create a trigger for the API call.

  1. On the Attendee object definition page banner, click Triggers, then click New Trigger.

  2. Set up the trigger:

    • For the Trigger Type, choose Intacct API and click Next.

    • Select This trigger is deployed.

    • For Trigger Activation, click After Create.

    • For Trigger Name, enter Create_Sales_Order.

  3. Under Trigger Type Properties, click the plus sign to add a new document template.

  4. Enter Conference registration sales order as the Template Name.

  5. Paste your working create_sotransaction function (created above) into the code editor area.

  6. Use a merge field to include the year created for the date due:

    • Under Available Merge Fields, choose Attendee as the field type and Year created for the field. The token displays: {!MCA_attendee.year_created!}

    • Copy and paste the token into the year child element of datecreated into the code editor area.

      copy merge field in UI

  7. Use the same approach for the month and day elements:

    <month>{!MCA_attendee.month_created!}</month>
<day>{!MCA_attendee.day_created!}</day>

  8. Set up the datedue elements as follows:

     <datedue>
     <year>{!MCA_attendee.year_due!}</year>
     <month>{!MCA_attendee.month_due!}</month>
     <day>{!MCA_attendee.day_due!}</day>
 </datedue>

  9. From the Available Merge Fields, choose Related Conference level, then set up the price element as follows:

      <price>{!R_attendee_conference_level.price!}</price>

  10. From the Available Merge Fields, choose Attendee, then set up the customerid element as follows:

      <customerid>{!MCA_attendee.RCUSTOMER!}</customerid>

  11. Provide the transaction type (must be a valid transaction type in the company):

      <transactiontype>Sales Order</transactiontype>

  12. Just to make it easy for us to find a sales order during our testing, use an easy-to-find field name for referenceno:

      <referenceno>ABC test</referenceno>

  13. Fill in any other missing parameters and click Save.

    Your completed call will look something like this:

       <create_sotransaction>
     <transactiontype>Sales Order</transactiontype>
         <datecreated>
             <year>{!MCA_attendee.year_created!}</year>
             <month>{!MCA_attendee.month_created!}</month>
             <day>{!MCA_attendee.day_created!}</day>
         </datecreated>
         <customerid>A11</customerid>
         <referenceno>ABC test</referenceno>
         <datedue>
             <year>{!MCA_attendee.year_due!}</year>
             <month>{!MCA_attendee.month_due!}</month>
             <day>{!MCA_attendee.day_due!}</day>
         </datedue> 
         <state>Pending</state>
         <sotransitems>
             <sotransitem>
                 <itemid>Conference registration</itemid>
                 <warehouseid>East</warehouseid>
                 <quantity>1</quantity>
                 <unit>Each</unit>
                 <price>{!R_attendee_conference_level.price!}</price>
             </sotransitem>
         </sotransitems>
   </create_sotransaction>

  14. Scroll to the bottom of the New Trigger page and click Save.

Test the trigger

  1. Create a new attendee in the application.

  2. Go to Order Entry > All > Sales Order and search for the new transaction by Reference number, ABC test.

Troubleshooting

If the Sales Order is not found, it means there was an issue with the API call. You can’t debug the call inside Platform Services, but you can use Postman to help figure out the problem:

  1. Go back to your original working create_sotransaction call with the hard coded parameter values in Postman.

  2. Compare this version to the template version of the call and look for discrepancies.

  3. If you don’t see any issues, begin replacing the merge-field values in the template with the appropriate hard-coded values from your working call. Each time you do this, upload the updated template and create another attendee. Repeat this until the sales order is created. This means the last replaced merge field was problematic.

What’s Next?

Provide feedback