How to set up Spektrix Connect as an Agent system

Rachael Norris
Rachael Norris
  • Updated

To start selling tickets for another organisation using Spektrix Connect, you’ll need to set up the connection between an Agent and a Source System. You can then import Event Instances into the Agent System and configure the remaining Event information.

User Permissions General Administrator User Role
Availability Early Access - contact support

Before starting, make sure you’re familiar with:

How do I set up Spektrix Connect as an Agent System?

There are four steps:

  1. Connect
  2. Import
  3. Map
  4. Complete Event Configuration

1. Connect

Follow the instructions depending on the type of Source System you want to connect:

  • A Spektrix Source System
  • A non-Spektrix Source System

TIP: This article contains instructions for the Agent System using Spektrix Connect. The Source System organisation will need to follow the steps in How to set up Spektrix Connect as a Source System.

  • A Spektrix Source System

    To set up a connection to a Spektrix Source System, you will need:

    The Source System’s organisation will need to set your organisation up as an Agent Customer Record and make the agreed Instances available to sell via the API.

    To add a new Spektrix Source System:

    1. Go to Settings Interface > Configuration > Source Systems.
    2. Click New Source System.
    3. Enter the Source System’s organisation name. This will only be displayed on your system.
    4. In Type, select Spektrix.
    5. Enter the client name of the other organisation's Spektrix system.
    6. Enter the API user and API key from the key generation tool.
    7. Click Create Configuration:

    WARNING: Copy the API key exactly as shown in the key generation tool. If the key is incorrect, imports will fail and you'll receive an import failure email asking you to check the Source System setup.

  • A non-Spektrix Source System

    A developer needs to build and host an HTTP Connector before you can add the connection in Spektrix.

    To set up a connection to a Source System using a HTTP connector, you will need:

    • The connector’s Base URL
    • Authentication header name and value

    Both should be provided by the developer who has created the connector.

    To add a new HTTP connector Source System:

    1. Go to Settings Interface > Configuration > Source Systems.
    2. Click New Source System.
    3. Enter a Name for the Source System. This will only be displayed on your system.
    4. In Type, select HTTP Connector.
    5. Enter the Base URL of the connector. This must be a full web address beginning with https://.
    6. Enter the Authentication header name and Authentication header value the developer has given you.
    7. Click Create Configuration:

    When you open an existing HTTP Connector Source System, the Required endpoints link takes your developer to the list of endpoints their connector must provide.

How to edit a Source System Connection

To edit a Source System connection, go to Settings Interface > Configuration > Source Systems and click Edit next to the Source System you want to change.

You can change the Name, Type and connection details. For security, the API key and Authentication header value are hidden. Leave them as they are to keep the existing value, or enter a new value to replace it.

You will need to update the API key if the other organisation resets it.

Once you have made changes, click Update configuration.

Order follow up emails

If an Order is confirmed in your system but can't be confirmed in the Source System, or the price confirmed by the Source System doesn't match, you’ll receive an order follow up email.

To configure follow up emails:

  1. Go to Admin Interface > Source Systems.
  2. In the box labeled Enter email addresses you want to receive notification of orders requiring follow-up action, enter one or more email addresses separated by commas:

    TIP: We recommend using a shared email address at your organisation for both lists so that notifications aren't missed when someone is away.

  3. Click Save.

2. Import

Once you’ve added the connection you can import Events and Instances from the Source System:

  1. Go to Admin Interface > Other > Source Systems.
  2. Select the Source System you want to import Events from.
  3. Find the Event in the list of Events available to import.

  4. Select Import Event.

You’ll then see a confirmation message banner confirming how many Events and Instances have been imported:

 

Bulk Import

To import or update multiple Events and Instances you can use the functions in the Bulk Import section:

Check the box against the operation you want to run:

  • Import New Events: Imports newly available Events and their applicable future Instances.
  • Add Missing Instances: Adds newly available Instances to Events you’ve already imported.
  • Update Existing Instances: Updates imported Instances, including changes to dates, cancellations, removals and layouts.
  • Validate Mappings: Checks for mapping problems affecting imported Events and Instances.

To run the selected operations, click Run selected imports.

You’ll see a Job Submitted in the top right of the screen. Hover your mouse over the green check mark and click to download the file. Once downloaded you’ll be able to view the results by opening the file:

In the file, you’ll see a tab representing each operation and a line for each of the created or updated Instances.

REMINDER: Update Instances on an individual imported Event updates its existing Instances. Use Add Missing Instances to bring in newly available Instances.

How do I configure automatic imports and updates?

To configure automatic imports and updates:

  1. In the Settings Interface, go to Configuration > System Setup > Source Systems.
     
  2. Select the operations you want the hourly job to run:
    • Import new events
    • Add missing Instances
    • Update existing Instances
    • Validate mappings
       
  3. Enter an email address to receive failed import notifications in the Enter email addresses to receive notification in the event that the hourly sync fails box. You can enter one or more email addresses separated by commas.
     
  4. Click Save Configuration:

These settings apply across all of your configured Source Systems. They also provide the initial operation selection when you run a one off import.

 

What happens if the Source System cancels an Instance?

If an Instance in the Source System is cancelled, the next update cancels it and takes it off sale in your Agent System too. You should work with the Source System organisation to agree on messaging and timelines for communication.

The Agent System organisation is responsible for contacting customers and issuing refunds. Depending on whether payments for a canceled Instance have already been invoiced and paid to the Source System, you may need to redistribute costs between the two organisations.

 

3. Map

Spektrix uses Mapping to translate each sale between the two systems. Before selling, you must match the Source System's Ticket Types, Price Bands and Lock Types to your own.

Each Mapping links one of the Source System's items to one of yours. You can't map two Source System items to the same item of yours, or the other way round.

Spektrix uses mappings in both directions:

  • When displaying a Seating Plan, it shows your Ticket Types and Price Bands against the Source System's live prices.
  • When a ticket is added to the basket / cart, it tells the Source System which of its Ticket Types to sell.

Seats in an allocation that haven’t been matched to a Lock Type in the Agent system won’t be available for sale. And, for each Price Band the default Ticket Type must be mapped for the Instance to be able to be sold.

To map an item, go to the Admin Interface > Other > Source Systems and select the Source System.

For each item:

  1. Select the source item from the unmapped source dropdown.
  2. Select the equivalent item from your system.
  3. Click Add.
  4. Repeat for the other items.

Once added, the Mapping appears under Existing mappings. Each page shows how many items are mapped and how many of the Source System's items are still available to map.

To remove a Mapping, click Remove mapping next to it. Once removed, the items become available to map again. To change a Mapping, remove it and add a new one.

WARNING: If a Mapping is removed or changed while tickets using it are in an Open Transaction, the Basket / Cart can't be completed. Staff will see a message such as The mapping for one or more ticket types no longer matches. Try setting the ticket type again. For this reason you should avoid changing Mappings during busy selling periods.

 

Ticket Type Mappings

You will need to map each Ticket Type from the Source System to equivalent Ticket Types in your Agent System. These can be Ticket Types you already use to create a consistent experience for your customers. For example, you might match the Source System's Adult Ticket Type to your Full Price Ticket Type.

At a minimum you will need to map the Source System's default Ticket Type for each Price Band. If you don’t know which is the default Ticket Type and you don’t plan to map all Ticket Types, reach out to the Source System organisation for confirmation.

On your website, a mapped Ticket Type is only offered if the corresponding Ticket Type in your system is set to be available on the web. This lets you sell some Ticket Types at your box office only, for example a Companion Ticket Type.

If you do not map a Ticket Type it will not be available to sell on your Agent System.

When all Ticket Types are mapped in one or both systems, you'll see There are no unmapped ticket types left to add.

 

Price Band Mappings

You will need to map every Price Band the Source System uses for the Event Instances you sell on your Agent System.

If any Price Band used by an Instance isn't mapped, no seats can be sold for the Instance.

When all Price Bands are mapped, you'll see There are no unmapped price bands left to add:

 

Lock Type Mappings

Seats under an unmapped Lock Type can't be sold, so you’ll need to map all seats in Lock Types that you want to sell. Seats under a mapped Lock Type follow the rules of your Lock Type, for example whether a password is needed, or which customers are eligible.

Lock Types are discovered as seat availability is read from the Source System once a seating plan using it has been opened in your system.

To map a Lock Type:

  1. In the Sales Interface, open the Seating Plan of an imported Instance. This will discover and recognise the Instance’s Lock Types.
  2. Add the Mapping on the Lock Types.

To map Lock Types, go to the Admin Interface > Source Systems > choose the Source System you want to create the mapping for > Lock Types. Then, add a mapping for each of the Lock Types.

 

Validating Mappings

Before you are able to start selling, you will need to run the Validate Mappings operation and review the results.

To do this go to the Admin Interface > Source Systems and then choose the Source System you want to check.

  1. Under Bulk Import, check Validate Mappings. Uncheck the other options if you only want to check Mappings:

  2. Click Run Selected Imports.
  3. Open the report from your running reports list and go to the Mapping Validation tab.

The tab lists each future Instance that can't be sold because of missing Mappings, with the problem, for example:

Ticket type and price band mappings for 'City Theatre' are incomplete (price bands: Band C; ticket types: Adult). Configure them in Admin > Source Systems.

Sales Users will also see this message when they open the Seating Plan of an Instance with Mapping issues.

If you don’t have enough items to map to the Source System, you'll see Source values are still available, but there are no unmapped local values left. In this situation, you will need to create another Ticket Type, Price Band or Lock Type in your system, or remove an existing Mapping.

If your Spektrix system can't reach the Source System, you'll see Could not load this list from the Source System. Your existing Mappings are still shown, and you can add new ones when the Source System is available again.

TIP: The validate mappings operation runs every hour by default. You should also run it after importing new Events, and whenever the Source System organisation tells you they've added a new Ticket Type or Price Band.

 

4. Complete Event configuration

Next, you’ll need to complete the details about your Events and Instances in your Agent System.

Complete the following steps:

  1. Add Event details. Add an Event description, images and any Event Attributes you use for your website or reporting. Add any local Event information needed for web or Box Office sales.
  2. Configure the start selling time of Instances. Choose when and how tickets will be sold (online or in the Sales Interface).
  3. Apply a Ticket Commission Structure (optional). Apply your own Commission Structure if you want to add a commission on top of the Source System's price.
  4. Check your Ticket Design, E-tickets or Digital Pass Templates. Make sure the Ticket Design prints the barcode, so tickets can be scanned at the Source System's venue. If your organisation’s Ticket Design includes address details you should create and use a different template.

 

Before selling

Before you start selling, we recommend that you:

  • Check the imported Events, Instances, Venues and Seating Plans
  • Resolve Mapping problems
  • Check availability, Ticket Types, prices and commissions
  • Complete a test sale through each sales channel you plan to use
  • Ask the source venue to confirm that its scanners and admission system accept the Tickets
  • Agree how to escalate queries or refund requests between your organisations

To learn more about selling tickets, read Selling Tickets via Spektrix Connect.