Configure

Create the integration

Follow these steps to get the integration initially configured.

  1. In your Lineup Ninja event, navigate to  Publish Agenda and then click the ‘Publish’ button under ‘JSON’. This will create a new publication.
  2. A screen will pop up where you can enter a username and password to secure the endpoint. You can also input the ‘Webhook URL’ you would like Lineup Ninja to call when the agenda is published. Save the configuration.
  3. Now click ‘Publish’ to publish the agenda to the URL shown on the screen.

Fetch the data

Perform a GET to the URL shown after publishing your event. If you have configured a Username and Password for the agenda you must provide these as HTTP Basic Auth on your request.

Files

The integration can be configured to include links to files attached to speakers, sessions, labels, locations, resources and tracks. You can choose to include all files, or just files of a particular type.

Note

If you include links to uploaded files in a JSON publication then the links are unique for that publication.

If you delete the JSON publication the links will stop working. This means you can revoke access to files that were previously shared be deleting the publication.

Schema

Note

As our product develops we will add new fields to the schema without notice.

Where possible we will not deprecate or remove existing fields, if this becomes required we will notify active users of the integration.

These are the typescript definitions for the document.

Note that ‘speakers’ are called ‘contributors’ in the document.

{
    /**
     * Contributors are the speakers for the event
     */
    contributors: Contributor[];
    /**
     * Labels, aka tags, can be assigned to contributors, sessions, tracks, resources and locations
     */
    labels: Label[];
    /**
     * Locations are where sessions take place
     */
    locations: Location[];
    /**
      * Resources are things that sessions need. Locations can have resources assigned to them.
      * Sessions are then required to be scheduled in a location with matching resources.
      */
    resources: Resource[];
    /**
     * Roles model the relationship between contributors and sessions, eg Chair, Panel Member etc...
     */
    roles: Role[];
    /**
     * Sessions are sessions....
     **/
    sessions: Session[];
    /**
      * A session can take place in one or many tracks.
      */
    tracks: Track[];
}

Contributor (aka Speaker)

  {
    /**
     * The UUID for the speaker
     */
    id: string;
    /**
     * The speaker's title eg Mr, Mrs, Mx...
     */
    honorific: string | null;
    /**
     * The speaker's first name
     */
    firstName: string | null;
    /**
     * The speaker's last name
     */
    lastName: string | null;
    /**
     * Any letters after the speaker's name, eg 'Esq', 'OBE' etc...
     */
    postNominal: string | null;
    /**
     * The speaker's email. Note that some speakers may not have an email address, it is also not guaranteed to be unique.
     */
    email: string | null;
    /**
     * The speaker's company
     */
    company: string | null;
    /**
     * The speaker's job title at their company
     */
    position: string | null;
    /**
     * The speaker's phone number
     */
    phone: string | null;
    /**
     * The speakers country code, eg 'gb'
     * The data is sourced from https://www.iso.org/obp/ui/#search/code/
     * Our current dataset can be found here https://app.lineup.ninja/countries.json
     */
    countryCode: string | null;
    /**
     * The speakers country name, eg 'United Kingdom'
     * The data is sourced from https://www.iso.org/obp/ui/#search/code/
     * Some names are tweaked to improve presentation eg 'United Kingdom', rather than 'United Kingdom of Great Britain and Northern Ireland (the)'
     * Our current dataset can be found here https://app.lineup.ninja/countries.json
     */
    countryName: string | null;
    /**
     * The URL for the speaker's Twitter feed
     */
    twitter: string | null;
    /**
     * The URL for the speaker's Facebook page
     */
    facebook: string | null;
    /**
     * THe URL for the speaker's LinkedIn page
     */
    linkedin: string | null;
    /**
     * The URL for the speaker's Instagram page
     */
    instagram: string | null;
    /**
     * The URL for the speaker's Youtube channel
     */
    youtube: string | null;
    /**
     * The URL for the speaker's GitHub Profile
     */
    github: string | null;
    /**
     * The URL for the speaker's Website
     */
    website: string | null;
    /**
     * The speakers bio formatted in Markdown
     */
    bio: string | null;
    /**
     * The speakers bio formatted in HTML
     */
    bio_HTML: string;
    /**
     * A URL to the speakers headshot, 128x128px
     */
    headshotURL: string | null;
    /**
     * A URL for the speakers headshot at 256x256px
     */
    headshot2xURL: string | null;
    /**
     * A URL for the speakers headshot at 512x512px
     */
    headshot4xURL: string | null;
    /**
     * A URL for the speakers headshot at 1024x1024px
     */
    headshot8xURL: string | null;
    /**
     * A URL to the speakers company logo, to fit within 128x128px
     */
    logoURL: string | null;
    /**
     * A URL to the speakers company logo, to fit within 256x256px
     */
    logo2xURL: string | null;
    /**
     * A URL to the speakers company logo, to fit within 512x512px
     */
    logo4xURL: string | null;
    /**
     * A URL to the speakers company logo, to fit within 1024x1024px
     */
    logo8xURL: string | null;
    /**
     * The speakers availability
     */
    availability: Availability[];
    /**
     * The UUIDs of labels assigned to the speaker
     */
    labels: string[];
    /**
     * The UUIDs of sessions assigned to the speaker
     */
    sessions: string[];
    /**
     * A list of sessions and the role id for each session assigned to the speaker
     */
    sessionJoins: ContributorSessionJoin[];
    /**
     * Any notes for the speaker. These are generally intended to be kept private.
     */
    notes: string | null;
    /**
     * When the speaker was last modified in UTC.
     * eg 2022-02-04T18:03:03.662Z
     */
    lastModified: Date;
    /**
     * Any Data Sources referenced for this speaker
     */
    references?: SourceReferences | undefined;
    /**
     * Any data for Custom Fields for this speaker
     */
    customFieldData: CustomFieldData[];

    /**
     * Files attached to the speaker
     *
     * Note that files are not included by default. You can configure this per publication as required.
     *
     * For headshot and logo it is probably easier to use the headshot and logo properties above
     */
    files: File[];

    /**
     * If the speaker was created from a submission this will include the details for the submission
     * If a speaker was submitted to multiple submissions then there will be multiple origins
     *
     * This data exists for contributors created/updated after 16 June 2023
     */
    origins: ContentOrigin[]
}

Labels

{
    /**
     * The UUID for the label
     */
    id: string;
    /**
     * The name of the label
     */
    name: string;
    /**
     * A description of the label formatted in Markdown
     */
    description: string | null;
    /**
     * A description of the label formatted in HTML
     */
    description_HTML: string;
    /**
     * The UUIDs of contributors (speakers) assigned to this label
     */
    contributors: string[];
    /**
     * The UUIDs of locations assigned to this label
     */
    locations: string[];
    /**
     * The UUIDs of resources assigned to this label
     */
    resources: string[];
    /**
     * The UUIDs of sessions assigned to this label
     */
    sessions: string[];
    /**
     * The UUIDs of tracks assigned to this label
     */
    tracks: string[];
    /**
     * When the label was last modified in UTC
     * eg 2022-02-04T18:03:03.662Z
     */
    lastModified: Date;
    /**
     * Any Data Sources referenced for this label
     */
    references?: SourceReferences | undefined;
    /**
     * Any data for Custom Fields for this label
     */
    customFieldData: CustomFieldData[];

    /**
     * Files attached to the label
     *
     * Note that files are not included by default. You can configure this per publication as required.
     */
    files: File[];

}

Locations

{
    /**
     * The UUID for the location
     */
    id: string;
    /**
     * The name of the location
     */
    name: string;
    /**
     * A description of the location formatted in Markdown
     */
    description: string | null;
    /**
     * A description of the location formatted in HTML
     */
    description_HTML: string;
    /**
     * The availability of the location
     */
    availability: Availability[];
    /**
     * The UUIDs of labels assigned to this location
     */
    labels: string[];
    /**
     * The UUIDs of resources assigned to this location
     */
    resources: string[];
    /**
     * The UUIDs of sessions taking place in this location
     */
    sessions: string[];
    /**
     * The UUIDs of tracks taking place in this location
     */
    tracks: string[];
    /**
     * When the location was last modified in UTC
     * eg 2022-02-04T18:03:03.662Z
     */
    lastModified: Date;
    /**
     * Any Data Sources referenced for this location
     */
    references?: SourceReferences | undefined;
    /**
     * Any data for Custom Fields for this location
     */
    customFieldData: CustomFieldData[];
    /**
     * Files attached to the location
     *
     * Note that files are not included by default. You can configure this per publication as required.
     */
    files: File[];

}

Resources

{
    /**
     * The UUID for the resource
     */
    id: string;
    /**
     * The name of the resource
     */
    name: string;
    /**
     * A description of the resource formatted in Markdown
     */
    description: string | null;
    /**
     * A description of the resource formatted in HTML
     */
    description_HTML: string;
    /**
     * The UUIDs of labels assigned to this resource
     */
    labels: string[];
    /**
     * The UUIDs of locations with this resource
     */
    locations: string[];
    /**
     * The UUIDs of sessions needing this resource
     */
    sessions: string[];
    /**
     * When the resource was last modified in UTC
     * eg 2022-02-04T18:03:03.662Z
     */
    lastModified: Date;
    /**
     * Any Data Sources referenced for this resource
     */
    references?: SourceReferences | undefined;
    /**
     * Any data for Custom Fields for this resource
     */
    customFieldData: CustomFieldData[];
    /**
     * Files attached to the resource
     *
     * Note that files are not included by default. You can configure this per publication as required.
     */
    files: File[];

}

Roles

Roles model the relationship between contributors and sessions, eg Chair, Panel Member etc…

{
    /**
     * The UUID for the role
     */
    id: string;
    /**
     * The name of the role
     */
    name: string;
}

Sessions

{
    /**
     * The UUID for the session
     */
    id: string;
    /**
     * The name of the session
     */
    name: string;
    /**
     * A code for the session. This is created by the Event Manager, eg TECH101.
     */
    code: string | null;
    /**
     * A description of the session formatted in Markdown
     */
    description: string | null;
    /**
     * A description of the session formatted in HTML
     */
    description_HTML: string;
    /**
     * If the session is scheduled, the start date of the session in UTC
     * eg 2022-02-04T18:03:03.662Z
     */
    startDate: Date | null;
    /**
     * If the session is scheduled, the end date of the session in UTC
     * eg 2022-02-04T18:03:03.662Z
     */
    endDate: Date | null;
    /**
     * The duration of the session in milliseconds
     */
    duration: number | null;
    /**
     * If the session is scheduled, the UUID of the location it is scheduled in
     */
    location: string | null;
    /**
     * Any notes for the location. These are generally intended to be kept private.
     */
    notes: string | null;
    /**
     * The UUIDs of contributors (speakers) for this session
     */
    contributors: string[];
    /**
     * A list of contributors and the role id for each contributor assigned to the speaker
     */
    contributorJoins: SessionContributorJoin[];
    /**
     * The UUIDs of labels assigned to this session
     */
    labels: string[];
    /**
     * The UUIDs of resources assigned to this session
     */
    resources: string[];
    /**
     * The UUIDs of tracks assigned to this session
     */
    tracks: string[];
    /**
     * When the session was last modified in UTC
     * eg 2022-02-04T18:03:03.662Z
     */
    lastModified: Date;
    /**
     * Any Data Sources referenced for this session
     */
    references?: SourceReferences | undefined;
    /**
     * Any data for Custom Fields for this session
     */
    customFieldData: CustomFieldData[];
    /**
     * Files attached to the session
     *
     * Note that files are not included by default. You can configure this per publication as required.
     */
    files: File[];
    /**
     * If the session was created from a submission this will include the details for the submission
     * A session may have multiple origins if multiple submissions were linked to it
     *
     * This data exists for sessions created/updated after 16 June 2023
     */
    origins: ContentOrigin[]

}

Note that a session may not yet be scheduled by the Event Manager. In this case it will not have a start or end time, nor a location.

Tracks

{
    /**
     * The UUID for the track
     */
    id: string;
    /**
     * The name of the track
     */
    name: string;
    /**
     * The description of the track formatted in Markdown
     */
    description: string | null;
    /**
     * The description of the track formatted in HTML
     */
    description_HTML: string;
    /**
     * The color of the track formatted in HEX
     * eg #FF00B1
     */
    color: string | null;
    /**
     * The UUIDs of labels in this track
     */
    labels: string[];
    /**
     * The UUIDs of sessions in this track
     */
    sessions: string[];
    /**
     * When the track was last modified in UTC
     * eg 2022-02-04T18:03:03.662Z
     */
    lastModified: Date;
    /**
     * Any Data Sources referenced for this track
     */
    references?: SourceReferences | undefined;
    /**
     * Any data for Custom Fields for this track
     */
    customFieldData: CustomFieldData[];
    /**
     * Files attached to the track
     *
     * Note that files are not included by default. You can configure this per publication as required.
     */
    files: File[];

}

SessionContributorJoin

A session may have multiple contributors with different roles, eg chair or panel member.

{
    /**
     * The UUID of the contributor
     */
    contributor: string;
    /**
     * If the contributor has a specific role in this session then the UUID of their role. Null otherwise
     */
    role: string | null;
}

ContributorSessionJoin

A contributor may have different roles across different sessions, eg they may be a chair for one session and a panel member in another.

{
    /**
     * The UUID of the session
     */
    session: string;
    /**
     * If the contributor has a specific role in this session then the UUID of their role. Null otherwise
     */
    role: string | null;

    /**
     * If 'Speaker Ordering' is enabled for the event, the position, or order, for this speaker in the session. Null otherwise
     */
    position: number | null;
}

Custom Field Data

An event may have Custom Fields. If data has been set for that item then the values will be returned in customFieldData

{
    /**
     * The UUID for this data
     */
    id: string;
    /**
     * The value for this data
     */
    value: string;
    /**
     * The UUID for this field
     */
    fieldId: string;
    /**
     * The type of field
     */
    fieldType:  'text' | 'textarea' | 'number' | 'checkbox' | 'radio' | 'email' | 'url' | 'date';
    /**
     * The name of the field
     */
    fieldName: string;
}

File

Files are attached to items on the agenda, they can be images, or regular files. For images cropped variants of the image may be available depending on the event configuration.

Note that files are not included by default. To add files browse to the configuration for the publication and set the ‘Do you want to include attached files in the feed’ option.

{
    /**
     * A unique ID for the file
     */
    id: string;

    /**
     * The name of the file
     */
    fileName: string;

    /**
     * The type of the file
     */
    type: {

        /**
         * This file type was created for this event
         */
        isPredefined: false;
        /**
         * The name of the file type eg 'Slides'
         */
        name: string;
        /**
         * A uuid for this file type
         */
        id: string;
    } | {

        /**
         * This is a predefined file type
         */
        isPredefined: true;
        /**
         * The name of the file type eg 'Speaker Profile Image'
         */
        name: string;
        /**
         * The type of predefined file
         * Additional types may be added from time to time
         */
        id: 'generic' | 'contributorHeadshot' | 'contributorLogo' | 'locationLogo' | 'locationSponsorLogo' | 'trackLogo'
    }

    /**
     * The size, in bytes, of the file
     */
    size: number;

    /**
     * The mimeType of the file
     */
    mimeType: string;

    /**
     * The URL to retrieve the file
     */
    url: string;

    /**
     * The variants of this file
     * For images these are the different sizes of image available
     */
    variants: FileVariant[];
}

FileVariant

Image files have ‘variants’ which are the image scaled to fit within

The properties are the same as a regular File with an additional scale attribute

File & {
    /**
     * The size the image was scaled to fit within
     * THUMB = 128x128
     * SMALL = 256x256
     * MEDIUM = 512x512
     * LARGE = 1024x1024
     * FULL = The same resolution as the originally uploaded image
     */
    scale: 'THUMB' | 'SMALL' | 'MEDIUM' | 'LARGE' | 'FULL';
}

ContentOrigin

Both Contributor and Session have origins property, which is any array containing the detail of which submissions this Contributor of Session was created from.

At present ‘submission’ is the only ContentOrigin type. More types may be added in the future, with different shapes, so do be sure to check that type === 'submission' when processing these.

Once a Contributor or Session has been created the original source of the object may become deleted. In which case deleted will be true in the respective entry below.

{
    type: 'submission';
    /**
     * The owner of the Submission. I.e. the Submitter
     */
    owner: {
        id: string;
        name: string;
        email: string;
        deleted: boolean;
    };
    /**
     * The name and id of the Submission from which this object was created
     */
    submission: {
        id: string;
        name: string;
        deleted: boolean;
    };
    /**
     * The event in which the submission exists
     */
    event: {
        id: string;
        name: string;
        deleted: boolean;
    };
    /**
     * The current stage of the submission, eg 'Submitted'
     */
    stage: {
        id: string;
        name: string;
        deleted: boolean;
    };
    /**
     * Any labels attached to the submission
     * This includes labels in the same event as the JSON publication and also labels in other events
     * So be sure to filter by event.id if you are only interested in fields in a particular event
     */
    labels: {
        id: string;
        event: {
            id: string;
            name: string;
            deleted: boolean;
        };
        name: string;
        deleted: boolean;
    }[];
}

Source References

If the event is using ‘Data Sources’ then a mapping between the URI of the source, and the ID’s of the objects at the source.

{ [sourceService: string]: string[] };

Webhook

If configured Lineup Ninja will call a webhook after a successful publish of the event. The webhook is called as a POST with this body:

{
    /**
     * The UUID of the event
     */
    eventId: string;
    /**
     * The name of the event
     */
    eventName: string;
    /**
     * The timestamp for the publication. You can use this to deduplicate calls to the webhook
     * It is in epoch time with milliseconds (A javascript timestamp)
     */
    publicationTimestamp: number;
    /**
     * The UUID for the integration. The customer may wish to configure multiple integrations per event,
     * for example to different staging and production events. this ID can uniquely identify them
     */
    integrationId: string;
}

How can I filter the published content?

You can filter which Speakers and Sessions will be published based on a number of criteria. Some common use cases for filters are:

  • Preventing ‘Placeholder’ sessions from being published
  • Holding back a Speaker who is not yet ready to be announced
  • Excluding sessions scheduled during the ‘build up’ day for the event
  • Only publishing speakers who have confirmed their slot
  • Removing a particular location, or track from the published schedule
  • Anything you can think of using labels!

For Speakers you can filter in 3 ways

  • Choose which speakers are to be published based on their relationship to sessions
    • (If Speaker Confirmation is enabled): Publish speakers that have a confirmed session that is published and not filtered out.
    • Publish speakers that are speaking on any session that is published and not filtered out.
    • Publish all speakers
    • Publish no speakers
  • Apply more granular filters with labels
    • Only publish speakers with a particular label. For example you might want to use a ‘Content Reviewed’ label to flag speakers that have had their content reviewed.
    • Exclude speakers with a particular label. For example you might want to exclude a ‘Do not publish’ label to prevent publishing of speakers who are not yet ready to be published.

For Sessions you can filter in numerous ways

  • Choose which sessions are to be published based on their relationship to speakers
    • Publish All Scheduled Sessions. Publishes sessions regardless of whether they have confirmed speakers or not.
    • (If Speaker Confirmation is enabled): Publish sessions that have one confirmed speaker.
    • (If Speaker Confirmation is enabled): Publish sessions that have all their speakers confirmed.
    • Publish All Sessions (available on Lineup Ninja Agenda App only)
  • Apply filters with labels
    • Only publish sessions with a particular label. For example you might want to use a ‘Content Reviewed’ label to flag sessions that have had their content reviewed.
    • Exclude session with a particular label. For example you might want to exclude a ‘Placeholder’ label to prevent publishing of sessions which are not yet populated.
  • Filter by location
    • Only publish sessions in a particular location, or locations. This can be useful if you are publishing an agenda for just one or two locations.
    • Exclude sessions in a particular location, or locations. This can be useful if you have scheduled sessions in your Green Room or similar back stage location.
  • Filter by resource
    • Only publish sessions needing a particular resource. This could be useful if you are producing an agenda for a particular team that manages some resources.
    • Exclude sessions needing a particular resource.
  • Filter by Date
    • Only publish sessions in a date or dates. Useful if you are producing an agenda for a particular day.
    • You can exclude a date or dates from your publication. Useful if you have dates for build up and tear down in your agenda.
  • Filter by Track
    • Only publish sessions in a particular track or tracks. Useful if you are producing separate agenda for separate parts of your event
    • Exclude sessions on a particular track. Can be useful to block presenting of a track until a product launch has happened.

To configure filters:

  • Click ‘Publish Agenda’
  • Click on the name for your existing publication
  • Click ‘Configure’
  • Expand the ‘Filter Speakers’ and ‘Filter Sessions’ sections and configure the filters you need
  • Save and republish

How can I merge locations, tracks and roles when publishing?

When publishing you can merge content together. This enables you to publish a simpler agenda for your attendees than the one you are using to plan your event.

You can choose to merge these types of data:

  • Locations. Merging location A into location B will show all sessions in location A as taking place in location B. This can be useful if you have multiple locations configured for scheduling purposes that will be experienced by the attendee as a single location.
  • Tracks. Merging track A into track B will show all sessions in track A as being in track B. This can be useful if you have some tracks with only a small number of sessions and wish to present this sessions as being in a more populous track.
  • Roles. Merging role A into role B will show speakers with role A has having role B. This can be useful if you have a lot of roles internally that are not intended to be shown to attendees. You can merge them into a role with a name appropriate for your attendees.

When merging the location, track, or role that you are merging into does not have to have any sessions itself. So you can use this to show a different name to attendees than you are using internally. For example you could create a ‘Main Hall’ location, and merge ‘Building B - Hall A’ into that location so attendees see ‘Main Hall’ in their agenda.

How can I embargo content that is not yet ready for the public?

You can choose to embargo session titles and descriptions if you have content that should only be shown to the public after being announced in the event.

An embargo is applied by using labels to identify the sessions that should have an embargoed session title or description.

For example if you have a label ‘New Product Launch’, you can configure an embargo to hide the session title and description from sessions with that label. Following the launch of the product you can remove the embargo and republish the agenda.

If you embargo a session or description you can replace the original text with something to indicate that the session will be published later, for example ‘Super Secret Session’.

The speakers for a session will still be shown when it is embargo’ed. To exclude a session, including it’s speakers from being published then use ‘Session Filters’ rather than an ‘Embargo Content’.

To configure an embargo:

  • Click ‘Publish Agenda’
  • Click on the name for your existing publication
  • Click ‘Configure’
  • Expand the ‘Embargo Content’ sections and configure the embargo that you need
  • Save and republish

How can I publish automatically?

Warning

Consider your teams workflow as a team before enabling automatic publishing. When you enable automatic publishing there is a potential for the agenda to be published when you have content that is not ready for publication.

Next - Integrate Agenda

Still can’t find what you’re looking for? Email support@lineupninja.com and one of the team will get back to you as soon as possible.​​​​​