Create custom attributes

📝 Note: If the AppDirect logo appears in the upper-left corner of the page, when Manage > Marketplace appears in this topic, click the grid icon > Switch to | Store, instead.

note

If the AppDirect logo appears in the upper-left corner of the page, when Manage > Billing and Distribution, or Manage > Developer appears in this topic, click the grid icon > Switch to | Distribution, instead.

A custom attribute is used to create a custom text field or checkbox through which you can collect information from marketplace users. When you create custom attribute fields and checkboxes you specify where they appear in the user interface. You can configure an API client to retrieve this information after a user enters information in the custom field or selects a checkbox.

Marketplace Managers can define the following types of custom attributes. Some might not appear as they are dependent on marketplace configuration.

• Company—Custom field or checkbox collects company-specific data, which is later retrieved using the Company API.
• User—Custom field or checkbox collects user-specific data, which is later retrieved using the User API.
• Order—Custom field or checkbox collects order-specific data, which is later retrieved using the Subscription API or the Purchase Order API and contained in the CSV download report generated from the following locations:
  • Manage > Marketplace > Dashboard > Billing | Orders > Download CSV
  • Manage > Developer > Bills > Billing Management | Subscriptions > Download CSV
  • Manage > Billing and Distribution > Bills > Billing Management | Subscriptions > Download CSV
• Product—Custom field or checkbox collects product-specific data, which is later retrieved using the Product API.
• Lead—Custom field or checkbox collects lead-specific data, which is later retrieved using the Lead API.
• Purchase—Custom field or checkbox collects purchase-specific data.
• Subscription—Custom field or checkbox collects subscription-specific data.

When you configure the custom field, you can define the following properties:

• Validation—Specifies whether entries in the custom field are validated, and if so, the type of validation used (alphabetic or alphanumeric).
• Field location—Specifies where in the UI the field appears, for example, on the Checkout page in the purchase flow, or on the company’s or opportunity details pages.
• Read and write access by user role—Specifies the user roles that can view and edit the field and its contents. For example, if you define a Reseller ID field, and give Resellers and Reseller Managers the ability to view and edit the field, the order can be updated with the ID of whichever user is working on the current stage of the sales cycle.

note

There is no logging or audit trail of the previous entries made in custom attribute fields.

Order and subscription custom attributes and opportunities

Some marketplaces collect information with order custom attribute fields during checkout, which they pass between integrated systems or include in reports. However, order custom attribute fields do not appear on the Opportunity details page. Instead, subscription custom attribute fields appear on the Opportunity details page. To address this discrepancy, create order and subscription custom attributes that have the same name and key. Information entered in subscription custom attributes fields (for example, on the opportunity details page) is automatically populated in the corresponding order custom attributes so that the information can be included in reports and passed between integrated systems.

• When marketplaces use or plan to adopt opportunities and create subscription custom attributes configured to appear on opportunities: for every subscription custom attribute, create an order custom attribute with the same key and type.
• When marketplaces adopt opportunities and use order custom attributes configured to appear in checkout: for every checkout order custom attribute, create a subscription custom attribute with the same key and type.

To create a custom attribute field or checkbox

1. Go to Manage > Marketplace > Settings > Custom UI | Custom Attributes. The Custom Attributes page opens.

2. Click Add Attribute above one of the following tables:

   • Company Custom Attributes
   • User Custom Attributes
   • Order Custom Attributes
   • Product Custom Attributes
   • Lead Custom Attributes
   • Purchase Custom Attributes (This is an AppDirect-enabled feature available to existing EU and US members of the Early Adopters' Program (EAP).)
   • Subscription Custom Attributes (This is an AppDirect-enabled feature available to existing EU and US members of the EAP.)
     The Add {type} Custom Attribute page opens.

3. Enter the following attribute data information in the corresponding field:

   • Key—Code to uniquely identify this custom attribute. This value becomes the API key used to retrieve the attribute value and also the database column name used in reports.
     This Key cannot be changed after the custom attribute is created.
   • Label—Users see this text above the custom attribute field.
   • Hint—Users see this text-based hint below the custom attribute field. You can use this field to suggest the format of the key. For example, if you are creating a Reseller ID field, and want the format of the key to be reseller-ID, you could use the hint to specify the format using a hyphen instead of an underscore.

4. Select one of the following options from the Input Type drop-down list:

   • Text—Adds a labeled text entry field to the location specified in step 7. If you select this option, continue this procedure with step 5.
   • Checkboxes—Adds a series of checkboxes to the location specified in step 7. When you select this option two additional fields and the Add Option button appear:
     1. Enter a checkbox label and a key for this checkbox in the corresponding fields. Each checkbox must have a unique key to identify the value of the checkbox similar to the key associated with this custom attribute.
     2. Click Add Option. Another pair of Checkbox Label and Key fields appear.
     3. Enter a checkbox label and a key for this checkbox in the corresponding fields.
     4. (Optional) Repeat step b and step c for any additional checkboxes. When the required number of checkboxes are added, continue this procedure with step 6.

5. Select one of the following validation options if you selected Text in step 4:

   • No Validation—The custom field accepts any number of letters, numbers, and special characters.

   • Character Type Validation—Define the validation rule as follows:

     1. Select Alphabetic (the field accepts any combination of characters a - z or A - Z), Numeric (the field accepts any combination of characters 0 - 9), or Alphanumeric (the field accepts any combination of characters a - z, A - Z, or 0 - 9).
     2. (Optional) Enter the maximum number of characters in the Character Count Limit field. For example, if you enter 8, a user cannot enter more than eight characters in the custom attribute field.
     3. (Optional) Select Use exact character count requirement to require that the Character Count Limit that you set (step b) is the only number of characters that a user can enter.

   • External System Validation—Validates the text entered in the custom attribute field against an external system. The external system must include the following in the response:

     • An HTTP status of 200. Any other response is treated as a failure and therefore, an invalid value. For example, a 500 response if the external system is unreachable.
     • For a valid custom attribute, a JSON object containing the field “statusCode” with the value “SUCCESS”.
     • For an invalid custom attribute, a status code value other than “SUCCESS”. You can map the different status codes to an appropriate error message as described in step f.

     Click Configure External Validation and define the validation rules as follows:

     1. Validation URL—This is the external validation endpoint. Enter the external system URL and add the tokens mentioned below:

        • {key}—This resolves to the custom attribute API key.

        • {value}—This resolves to the text the user has entered in the custom attribute field.

        • {type}—(Optional) This resolves to the entity type of the custom attribute. The possible values can be either USER, COMPANY, PURCHASE_ORDER (for Order Custom Attributes), or APPLICATION (for Product Custom Attributes).

        Note: Configuration of external validation URL when setting up the Subscription and Purchase Custom attributes is also available for Checkout V2.

        The text entered in the custom attribute field is passed as a query parameters in the validation URL. For example, you can set the validation URL as the following: https://external-validation-system.com/validate?type={type}&key={key}&value={value}.
        Then, at validation time, the URL queries an OAuth1 supported API endpoint and can be resolved to the following: https://external-validation-system.com/validate?type=COMPANY&key=resellerCompanyIdy&value=576425.

        Note the following in the previous URL example:

        • The type is Company, which is the type of custom attribute that is being validated against the external system.
        • The key is the resellerCompanyId, which was configured on the Add Company Custom Attribute page. This is used to uniquely identify this custom attribute. This value becomes the API key used to retrieve the attribute value.
        • The value is 576425, which is the text entered by the user in the custom attribute field.

     2. (Optional) Authentication type—Select OAuth, which is the type of authentication used to access the remote system.

     3. Consumer Key—Enter the OAuth1 consumer key used to query the external system. This identifies which application is making the request.

     4. Consumer Secret—Enter the OAuth1 consumer secret to query the external system. This is the client password used to authenticate with the server.

     5. Generic Error Message—Enter a simplified message for the user. For example, This is not a valid phone number.

     6. (Optional) Error Messages—Enter a customized error message that maps to the response error codes of the external system. This helps the user understand the error message rather than only seeing a status code. Click Add Error Message in the Error Messages section. Enter your customized error message and the corresponding status code.

        Note: Purchase custom attributes do not support validation.

6. Click Select a location. The Select a location drop-down list appears.

7. Click the Select a location drop-down list, then select the location where you want to add the custom field. The following table shows the location options available depending on the selected type of custom attribute.

   Attribute type	Available locations
   Company	Checkout (Additional Information and Confirm Order pages) Company Details page Company Signup My Company page Order details modal
   User	Checkout (Additional Information and Confirm Order pages) My Profile page Order details modal User Details page User Signup
   Order	Checkout (Additional Information and Confirm Order pages) Order details modal
   Product	Product editor (Additional Information section of the Manage Profile page) Product profile (Overview tab's Details pane)
   Lead	Leads Creation modal Leads Details page
   Purchase	Checkout (New)—applicable only to marketplaces that use Checkout version 2 (v2) Opportunities
   Subscription	Checkout (New)—applicable only to marketplaces that use Checkout version 2 (v2) Opportunities

   The Role section appears and displays the roles available for the selected attribute type and location. The following table shows the role options available depending on the selected attribute's location.

   Attribute location	Available roles
   Checkout	Customer Support Reseller Reseller Manager Sales Support User
   Checkout (New) - only applicable to marketplaces that use Checkout v2	Customer Support Reseller Reseller Manager Sales Support User
   Company Details page	Customer Support Reseller Reseller Manager Sales Support
   Company Signup	Customer Support Reseller Reseller Manager Sales Support User
   My Company page	Customer Support Developer Reseller Reseller Manager Sales Support User
   Order Details modal	Customer Support Reseller Reseller Manager Sales Support
   My Profile page	Customer Support Developer Reseller Reseller Manager Sales Support User
   User Details page	Customer Support Reseller Reseller Manager Sales Support
   User Signup	Customer Support Reseller Reseller Manager Sales Support User
   Product editor	Developer
   Product profile	User
   Opportunities	Reseller Sales Support Representative (SSR)

   note

   The Marketplace Manager role is not included in any Role section, but has View and Edit rights for all custom attribute fields. Marketplace Managers are never required to make entries in custom attribute fields.

8. Click the View and Edit checkboxes next to the user roles you want to have view or edit access to this custom attribute field.

9. Click the Required checkbox next to the user roles for which you want to require an entry in this custom attribute field.

10. (Optional) Click Select a location, then repeat steps 5 through 7 to configure additional locations for this custom attribute field.

11. Click Save Changes. The custom attribute field is created and located in the specified locations.

This section also includes the following best practice topics:

• Create the Reseller ID custom attribute
• Retrieve the Reseller ID custom attribute

They describe a specific use case where Developers represented by reseller companies that work on multiple AppDirect-powered marketplaces can track orders from multiple marketplaces using a custom attribute.