Creating and Managing Apps

Create, edit, and manage apps and app versions on the Akana API Platform, and manage visibility.

How do I add an app?
How do I decide which security mechanism to use?
How does an app consume APIs?
How do I manage app visibility?
How does app versioning work?
How do I add an app version?
How do I edit an app version?
How do I delete an app version?
How do I delete an app?
How do I export an app?
What are the contents of the app export file?
How do I import an app from an export file?
How can I control the search results entry for my app?

How do I add an app?

If you're logged in to the Community Manager developer portal, in most cases you can add an app from top menu bar: APIs > Add API. See below.

In some cases, the APIs menu might not include this option. If the option isn't available to you and you need to add an app, contact the Site Admin.

You might also want to add an app in the context of a specific business organization on the platform. See How do I manage apps for my organization?

To add an app

Go to Apps > Add App. The Add App page displays.

Specify values for your app. The minimum values required are app name and description, version ID and version notes. Use the field descriptions below to help you make your choices:

Name	Description
App Name	A descriptive name for your app. When developing an app naming convention, note that your initial app name will be automatically assigned as the App Name for subsequent versions (for example, Version 1.0) and will be {App Name} {App Version Name}.
Summary	A brief, plain-text description of your app (optional). Text entered in this field is displayed in the list view. Note: The values you provide for Summary and App Description are used to construct search results. For more information, see How can I control the search results entry for my app? below.
App Description	A detailed description of your app. It's a good idea to include marketing, functional, and use case information. Note: The values you provide for Summary and App Description are used to construct search results. For more information, see How can I control the search results entry for my app? below.
Version ID	The app version name; for example, v1, Version 1.3.
Version Notes	A detailed description of your app version.
Avatar	You can optionally upload an avatar (icon) for your app. 75x75 pixels is the recommended size. For more information, see How do I upload and crop icons? Note: To remove an avatar that was already uploaded, see How do I remove an avatar image?
Tags	Tags or keywords that can be used to search for posts or tickets in the App or API Forums.
Visibility	Your app's visibility setting: Public, Private, or Registered Users.
App ID (on some systems)	A custom app identity for the current app definition. If left blank, the app will be randomly assigned an App ID (identity) in the format {fedmember} - {random-hex}. Notes: The AppID is not case-sensitive. If you're specifying the AppID, make sure you choose a unique set of character (numbers/letters). For example, if you have appid12345-acmepaymentscorp, you cannot add APPID12345-acmepaymentscorp. Once assigned, the App ID cannot be changed.
Shared Secret (on some systems)	A custom Shared Secret for the current app definition. If left blank, a shared secret is automatically generated. To view it, on the app's Details page, click Show Keys > Click to View. Depending on platform settings, the shared secret might be encrypted when displayed. A Shared Secret can be regenerated for a specific app using the Regenerate Key function on the app's Details page.
App Website	A URL for the website associated with the app. Must be a fully-qualified URL, including protocol. For example: http://www.mywebsite.com.

Click Save. The app information is saved and posted to the app's Details page.

Note: In some cases, if an extension is in place, additional fields might appear in the bottom section of the Add App page. If so, these additional fields collect information about your app. Fields might be required or optional and might be of various types such as text-based or numeric, multiple selection, or dates. If you have questions about any of these fields, check the in-page tooltip (question mark to the right of the field) for help.

How do I decide which security mechanism to use?

The security mechanism you choose for the messages your app will send to one or more APIs determines the level of security applied to the message. In general, a stronger security mechanism might include more setup or more processing on the part of your app. Your choices will be determined by such factors as the nature of your app and the nature of the messages your app will exchange with the API. For example, an app that processes financial transactions might require greater security than one that returns movie information.

In addition, the requirements or limitations of the specific API or APIs you are using are a key factor.

The platform supports the following security mechanisms:

HMAC Signature with Shared Secret
Hash/Digest with Shared Secret
RSA Signature with PKI
OAuth 1.0a
OAuth 2.0

Although the platform supports all of the above, a specific API hosted on the platform might not support them all. Check the API documentation for specific information about the security mechanisms supported.

For more information about the first three options, refer to App Security Options and Setup. For more information about OAuth options, refer to App Security.

How does an app consume APIs?

After you create an app, several tasks must be performed so the app can consume an API.

Task	Description
Identify APIs	First, you must identify APIs you would like to add to your app. This can be done by performing a search via the Search menu and browsing the APIs on the API > Details page of each API.
Provision App with Authentication Key	Next, you must provision the app with an authentication mechanism. When you create your app, an App ID and Shared Secret are automatically assigned. If you prefer to use PKI over Shared Secret to sign your app, you can generate an X.509 Certificate file (CER), or a Certificate Signing Request (CSR) and import it. See How do app credentials work?
Add APIs and gain access to Sandbox implementation	After determining which API you want to access, the next step is to submit an API Access Request to license an API and gain access to the Sandbox or Live implementation. This task is performed using the API Access Wizard accessible by clicking the Access link on the API > Details page of a selected API. Here you select the APIs which you would like to license. For APIs that require license agreement acceptance, you must review and agree to the terms of one or more license agreements before access will be granted. The Policies section allows you to select one or more SLA policies to be used for monitoring API performance and quota management. Access to Sandbox or Live implementations is, in most cases, automatically approved. The Sandbox or Live endpoints are available and visible in the Apps > My Apps > choose app > APIs page.
Build App	The next step is to build your app as per the API requirements in terms of the semantics and security requirements of the API. Refer to the API documentation in the API > Documentation section of your API for more information.
Configure the app's OAuth profile settings	If your app will be using OAuth, specify preferences and configure the branding settings for the Grant Authorization page that your users will see, on the App Details > OAuth Profile page.
Complete App Testing in Your Sandbox	Set up simulated user accounts and data in your sandbox and test your app.
Request Live Approval	When you are finished testing and ready to gain access to the API's Live implementation, request access using the API Access Wizard. Upon approval, you will be ready to make calls to the Live endpoints.
Update Application with Live Endpoint	When the status of the Live Endpoint is "Activated" you must then update your app with the Live implementation URL.
Activate	After the Live implementation endpoint is updated in your app, you can select Activate.

How do I manage app visibility?

When you create an app using Create a New App, you can control whether visibility of the app is Public or Private via the "Visibility" option. You can change app visibility based on your requirements using the Edit function on the app's Details page.

A public app is visible to all individuals that use the site, is searchable, and displays in the All Apps search filter.
A private app is visible to the creator, in the My Apps search filter, and to individuals that are members of the app team.

How does app versioning work?

You might need to have more than one version of your app. For example:

You might want to have one version for support and/or testing, and another version for your customers to use.
You might want to have variations of your app that use different APIs.
You might want to separate usage monitoring, discussions, and ticket management by app version.

Any member of the app team can create a new instance (version) of an existing app. You can have multiple app versions.

Creating the first app version

When you create an app, your app definition becomes the first version.

Adding another app version

After creating your app and first version, you can create an additional version. Go to Apps > My Apps > choose app > Details. On the left, click Add Version. Define values in the same way as you did for the original app.

Viewing App Versions

To choose a specific app version, select it on the Version menu: Details page, top right.

Team Management

App team members are team members for the entire app, including all versions. There is no separate team for an app version.

App Management

App versions can be managed using a variety of different tools available on the app's Details page.

How do I add an app version?

If you are on the team for a specific app, you can add a new version at any time.

To create a new app version

Go to Apps > My Apps > choose app > Details.

On the left, click Add Version. The Add App Version page is displayed, with the following fields:

Name	Description
App Name	A read-only field that displays the descriptive name for your app.
Summary	A brief, plain-text description of your app version (optional). Text entered in this field is displayed in the list view.
App Description	A read-only field that displays the detailed description of your app.
Version ID	The app version name; for example, v1, Version 1.3.
Version Notes	A detailed description of your app version.
Avatar	You can optionally upload an avatar (icon) for your app. 75x75 pixels is the recommended size. For more information, see How do I upload and crop icons?
Tags	A text box that allows you to enter tags or keywords that can be used to search for posts or tickets in the App or API Forums.
App ID	(in some systems) A text box that allows you to enter a custom app identity for the current app definition. If left blank, the app will be randomly assigned an App ID (identity) in the format {fedmember}-{random-hex}. Note that an App ID cannot be changed after it is assigned. You must create a new app version using the +Version function on the app's Details page and issue a custom app identity.
Shared Secret	(in some systems) A text box that allows you to enter a custom Shared Secret for the current app definition. If left blank, a shared secret is automatically generated and can be viewed using the Show Keys > Click to View function on the app's Details page. Depending on platform settings, the shared secret might be encrypted when displayed. A Shared Secret can be regenerated for a specific app using the Regenerate Key function on the app's Details page.
Visibility	Your app's visibility setting: Public, Private, or Registered Users.
App Website	A URL for the website associated with the app. Optional; if provided, must be a fully-qualified URL, including protocol. For example: http://www.mywebsite.com.

Specify the Version ID, Tags, App Runtime ID (auto-generated if not specified), Shared Secret (auto-generated if not specified), Visibility (Public/Private), Version Description, and App Website.
Click Finish.

Note: In some cases, if an extension is in place, additional fields might appear in the bottom section of the Add App Version page. If so, these additional fields collect information about your app. Fields might be required or optional and might be of various types such as text-based or numeric, multiple selection, or dates. If you have questions about any of these fields, check the in-page tooltip (question mark to the right of the field) for help.

How do I edit an app version?

You can change app version information using the Edit function in the app's Details page.

Note: In some cases, if an extension is in place, additional fields might appear in the bottom section of the app's Details page in a Properties section of the page. There is a separate Edit button to change these app properties. See To edit properties for an app version below. In many cases there won't be app properties.

To edit an app version

Go to Apps > My Apps > choose app > Details.
At the top right, choose the app version.
Click Edit. The Edit App Version page is displayed.
Optional: on the left, modify any of these fields:
- App name: A short and clear name to distinguish your app.
- Summary: A short, plain-text field for internal display of the app description.
- App Description: A concise description of the app that will attract users. Supports Markdown.
- Version ID: A short and clear name to distinguish the version; for example, v1.
- Version Notes: Supplementary information to describe the app version.
Optional: on the right:
- Upload an avatar for the app version.
- Change the parent organization by providing the new value in the Parent Organization Name field. Start typing the new organization name in the field. After the first three characters, the platform displays a list of matching organizations for you to choose from. For more information about organizations on the platform, see Organizations.
- Modify the Visibility value for the app.
- Enter a user-defined App ID.
- Add or update the shared secret key.
- Add or update the fully-qualified URL for your app's website.
Click Finish.

To edit properties for an app version

Note: Depending on platform configuration, additional properties for apps might vary or might not appear at all.

Go to Apps > My Apps > choose app > Details.
At the top right, select the app version.
In the Properties section, click Edit.
Edit the properties as needed. For help, refer to field-level help if needed. If you need additional assistance, contact the Site Admin.
Click Finish.

How do I delete an app version?

You can delete an app version on the app's Details page.

Note: If you want to delete an old version and add a new version, add the new version first. If you delete the only version, the app is deleted. If you add the new version, you can then delete the older version.

To delete an app version

Go to Apps > My Apps > choose app > Details.
From the Version drop-down at the top right of the page, choose the version you want to delete.
Click Delete Version.
At the confirmation message, click OK. The app version is deleted.

How do I delete an app?

When there is only one version of an app, and you delete it, the entire app is deleted. If there is more than one version, and you want to delete the app, you must delete each version separately.

Note: In some cases, the platform might be set up so that deleting an app requires Business Admin approval. If this is the case, and you attempt to delete the app, you will see a message that the deletion request has been sent for approval. The app is inactivated pending approval; at this point, only the Business Admin can make changes. When the Business Admin approves the request, the app is fully deleted. If for any reason the Business Admin denies the request, the app is restored to normal operation.

To delete an app

Follow the instructions in To delete an app version above.
The confirmation message warns you that deleting the last version deletes the app. Click OK to confirm. The app is deleted.

How do I export an app?

You can export information about an app to an external file. You can then import that file to another instance of the platform. One use of this feature is to move data from one environment to another, such as from a development environment to a testing environment.

You can choose to export information about a single app version or all app versions. You can also choose whether or not to export additional data associated with the app.

To export an app

Go to Apps > My Apps > choose app > Details.
Click Export.
In the Export dialog, choose export versions (current version or all versions) and choose export options. If you want to export all information about the app, check all boxes. You can choose to export the following additional data associated with the app:
- Export App PKI
- Export API Contracts
- Export App Team Members
  Note: the relationship of the user as an app team member is exported, but the user is not exported. The user must exist in the target environment. If the user does not exist when the information is imported, the app is created without that team member. From there it can be fixed in several ways: a) the user can sign up and be invited to be an app team member, b) the user can sign up and the app data can be reimported, c) another individual can be designated as an app team member.
Click Export.
Choose to save or open the export file. By default, the export package file is named application-export.zip and is saved to your default downloads folder.

What are the contents of the app export file?

The app export file includes all the core information about the app, as well as any of the optional additional information you specified.

The file has a very specific structure. It will generally include the following files at root level:

objectgraph.xml: An XML file that shows the relationships between resources.
objectdata.xml: An XML-based summary of all the data in the export file.
exportproperties.properties: a properties file showing which options were included in the export file.

If PKI information was chosen to be exported, it is stored in a separate pki subfolder.

How do I import an app from an export file?

Any member of the app team, or a Business Admin, can export information about an app to an external file. However, only a Business Admin can import.

If you need help with import functions, contact your Business Admin.

If you are a Business Admin, refer to How do I import site, app, or API information from an export file? for instructions.

How can I control the search results entry for my app?

Valid in Version: 2019.1.32 and later

When users are searching for your app in the All Apps list, or performing any search that will include your app in the search results, a snippet of information is displayed about your app in the search results.

The search results entry is an opportunity to showcase your app in a brief summary.

In earlier versions, the Community Manager developer portal displayed the copy from the App Description field for the search results entry. In 2019.1.32 and later, it supports keyword search in the Summary field also. To match a search term, it pulls the copy for the search results entry from a concatenation of both these fields in the app definition:

Summary
App Description

Note: For information about setting up the Summary and App Description fields, see How do I add an app? above.

The search functionality works in the same way for apps and for APIs. For more information about how the search results entry is constructed, with examples, see How can I control the search results entry for my API?