1TAHI CREATING AND CONFIGURING TAHI ENABLED APPS

Creating and Configuring Tahi Enabled Apps

1TAHI CREATING AND CONFIGURING TAHI ENABLED APPS

Creating and Configuring Tahi Enabled AppsThis document will guide you through the steps required to create, configure and update apps within Tahi. Before getting started please ensure;

• You have completed the Provider Sign Up process. This would have provided you (as your company’s Nominated Super User) with the following via email;

- Login details - Test accounts for the Test and Production environments

• You have familiarised yourself with Tahi School Administration documents which can be found here. (This will be helpful knowledge when testing of your application).

Please Note: All of the screens in this guide are viewable only when logged in as a Provider user.

When you first log in to Tahi your landing page will look like this:

Configuration Section Overview

The configuration section for providers includes the following tabs:

SummaryThe Summary tab displays a panel and a ‘New User Details’ button. The space occupied by the panel will be populated by a summary listing that shows which schools have enabled your app and the number of users the app is enabled for. This feature is expected later in 2016.

Please Note: As the Super User for your organisation you would have received your test user account details via email. However, you can also export test account credentials using the ‘New User Details’ button, which will allow you to download login details for your test user accounts.

Once you have assigned your test users and a user has signed in and reset the their passwords, their test account details will no longer be included in the the new user details export.

2TAHI CREATING AND CONFIGURING TAHI ENABLED APPS

Manage GroupsThis can be used to create groups for the purpose of testing your apps. In schools these groups will represent subjects, classes, departments, and general groups which users are members of, as found in their student management systems. Here groups can be manually created and assigned to users under the User Administration section to allow you to test your app.

New AppsIn this section you can create and configure Tahi enabled applications. Once completed the app request will be sent to the N4L provider team for approval.

Published AppsThis section will show any apps that have been published by your organisation, and are available for schools to select and enable. Selecting the cog above each icon will open up the configuration screen for that app and allow you to make any necessary changes.

Denied/Decommissioned Apps Any apps which have have their integration justification rejected will appear here. Once an app is denied or decommissioned you cannot make any changes to the app.

3TAHI CREATING AND CONFIGURING TAHI ENABLED APPS

Creating a New Application

In order to create a new application you need to perform the following steps;

1. Click the ‘Create Application’ button on the ‘New Apps’ screen.

2. You will then be directed to the ‘New Application Configuration’ form shown below.

Complete the name, description, icon, contact name and contact email fields with the details that are relevant for your organisation. These details will be visible to school Tahi Administrators and users.

Use the browse option to search for and select the correct icon for your app which should be no larger than 60x60px

Please Note: We suggest that the contact email address which is entered should be the support email address for the app rather than the personal email of any individual in your organisation.

3. Select which ‘Integration Level’ you need in order for your application to fully function. Integration levels determine what information an app can access. Details on what information is available can be found here.

Please Note: The authentication protocols available are determined by the selected integration level.

4. You must provide a justification (for your app & it’s integration level) which needs to include enough information for N4L to assess and determine whether the app will be accepted into Tahi. The N4L team may contact you if they require additional information to make a decision.

4TAHI CREATING AND CONFIGURING TAHI ENABLED APPS

Please Note: Users privacy is extremely important and therefore apps without sufficient justification will not be permitted in.

5. After completing all of the required fields, select the ‘Save’ button.

6. A confirmation message will appear giving you an opportunity to correct any details before submitting your app for

approval as shown below.

7. Click ‘Yes’ to confirm your initial app settings. A successful submission message will appear and your app will then show in the ‘Pending Approval’ panel.

5TAHI CREATING AND CONFIGURING TAHI ENABLED APPS

8. If your app is approved, your organisation will receive an approval email within 2 business days and be invited to configure your application. The email will be sent the Super User email in the provider settings. This may or may not be the email address listed in the app configuration.

It will look similar to this:

Use the links in the email to connect to further integration documentation or to log directly into Tahi and configure your app.

Please Note: If your app is denied you’ll receive an email stating the reason and the app logo will move from the ‘Pending Approval’ panel to the ‘Denied’ panel of the ‘Denied/Decommissioned App’ tab.

Configuring an Approved Tahi Enabled App

Once you have received the approval email from N4L, follow these steps to configure your app.

1. In the ‘New Apps’ section, your app will now be visible in the ‘Approved for Configuration’ panel. Click on the cog above your app icon to configure the application.

2. The ‘Application Configuration’ panel, as shown below allows you to complete the required configuration details and also update previously entered information, except the integration level.

6TAHI CREATING AND CONFIGURING TAHI ENABLED APPS

Please Note: In our example the authentication protocol has already been set to OAuth as integration level 2 was selected in the initial application setup and therefore an API key and secret have also been automatically generated. You will need to include these details in your app as per the instructions in the Provider Integration Guide, which can be found here.

Once you have published the app, the API secret is hidden for security reasons.

3. For OAuth integrated apps at least one authorised redirect URI must be entered. If required, cross domain resource sharing domains can also be included. Multiple entries can be made for each of these fields.

4. If you app is integrated using SAML, you will need to:

• Download the Tahi IdP metadata• Download the SP metadata template and make the necessary changes to the file based on your apps

configuration requirements.• Upload your SP metadata file with your apps configuration using the provided template.

5. Once you have completed all of the necessary fields for configuration, click the ‘Publish’ button. You will see the usual confirmation message and the system will give you the opportunity to download your OAuth credentials, as shown in the screenshot below.

7TAHI CREATING AND CONFIGURING TAHI ENABLED APPS

6. Click the ‘Download Credentials’ button, a text file will be downloaded to your computer.

7. Save the file securely as this contains your OAuth API key and secret. These credentials are highly sensitive and specific to your organisation and will need to be configured within your OAuth enabled app as soon as possible.

The app will now be displayed in the ‘Published Apps’ screen.

Updating an App

There are a number of reasons a published app may require an update. For example the app’s support contact details, icon or description may need updating.

To update a published app, follow these steps: 1. Go to the app in ‘Published Apps’.

8TAHI CREATING AND CONFIGURING TAHI ENABLED APPS

2. Click on the cog to open the ‘Application Configuration’ form.

3. In the ‘Application Configuration’ form, make any required changes.

Please Note: In this form, you cannot change the ‘Integration Level’ of an app. To change the integration level please contact the N4L Helpdesk.

4. Click ‘Save’ to complete any changes.