HP PrintOS is a print production operating system with web and mobile apps that help you get more out of your HP presses and printers and simplify production. Operating systems provide an environment for application developers to add value to customers. Internally, HP has built nearly 20 applications on top of PrintOS. This document describes integration options for external application developers.
This SDK provides facilities for third-party application developers to integrate their applications into PrintOS. When using this SDK:
- Applications are hosted under their own domains (not owned by HP)
- Applications have their own HTTPS certificates tied to the app developer
- Applications appear in the PrintOS Marketplace and may be purchased by PrintOS customers
- Purchased applications appear in the PrintOS app switcher so users can easily navigate to them
- Applications have access to basic user information...
- Name and contact info
- Role (user, admin, read-only)
- Preferences
- ...and organization information
- Name
- Organization type
- User membership
This document describes basic concepts and provides links to more detailed reference information.
Table of Contents
- PrintOS Concepts
- User Authentication
- Application Header Bar
- User Transfer Query Parameters
- Typical Interaction Sequences
- Marketplace Integration
- Example Application
- PrintOS APIs
PrintOS Concepts
For developers that are interested in building an application on PrintOS, it is important to understand some terminology and core concepts of the PrintOS platform.
Multi-Tenancy
In the cloud software world, the term "software multitenancy" refers to a software architecture in which a single instance of software runs on a server and serves multiple tenants. A tenant is a group of users who share a common access with specific privileges to the software instance.
For PrintOS, we have a single instance running in the AWS Cloud and we serve tenants--Print Service Providers (PSPs) and Channel Partners--around the globe for our Graphics Solution Business. This includes customers with our DesignJet, Indigo, Latex, Page Wide Press, and Scitex products.
While the scalable PrintOS application infrastructure is common for all users, customer data is linked to individual accounts and kept separate so customers cannot see each others' data.
Organizations
In PrintOS, a tenant is called an organization. A PrintOS organization may be either a Print Service Provider (PSP) or a Channel Partner/Reseller. Each organization has its own users, devices, sites, shifts and other related data.
Users
Each person who uses PrintOS has their own user account. These users are invited into organizations. In the simplest case, each user is a member of a single organization. When they log in, they see data only for that organization and can access that organizations applications and devices.
It is possible for a single user to have membership in multiple PrintOS organizations. This is used when one customer wishes to have multiple organizations to keep their data separated or when one person has business relationships with multiple PSPs.
Roles
Each user has one or more roles associated with their account. A user's roles control the data that user may access and the operations he or she may perform in PrintOS. PrintOS has a complex set of predefined roles that may be assigned to users (Administrator, Manager, Operator, CSR, etc.) The role structure can be quite complex, but each application maps the users roles down to a smaller set of concrete permissions for that application.
Often, we find that applications are well served by mapping the many roles in PrintOS down to only three roles in the application:
- User - Can use the application
- Administrator - Can configure the application and change settings
- Read-Only - Can view, but not change data
For applications integrated through our partner SDK, we will typically set up these mappings by default. More complex mappings are possible.
Sessions
When a PrintOS user logs in, PrintOS creates a token that is used to track the user's session. This token is usually stored in an HTTPS-only secure cookie and included in every API call from the browser. PrintOS services use this session token to identify the user, control access to APIs and select the correct organization's data.
Since the session cookie is secure and tied to the PrintOS domain, it is not accessible by partner applications. Instead, each partner application can log the user in using our standard OAUTH2 infrastructure (HP ID) and then use the resulting Access Token to request a PrintOS session that may be used by that application on its own domain.
Context
While a PrintOS user account may be linked to multiple organizations, a logged-in user can only operate in one account at a time. When the user first logs in, they must select one of the linked organizations, and this organization is set as the session context. While using that session, the user will only see data for that organization.
If the user wishes to work in a different organization, they must switch to a new context. When the user switches, a new user session is generated, linked to the new organization. The user will then operate in this new context and only see data for the linked organization.
If the user has logged in previously, we can automatically select the user's most recent context and use that as the default context at login.
Since the context is tracked in the user session, and each partner application manages its own session, the user's context is not transferred automatically. When the user navigates back and forth between PrintOS and partner apps, the user and organization IDs are passed as query parameters on the URL, and this allows the partner app to keep them in sync. This is a user convenience and should not be considered a security mechanism.
Applications
The PrintOS platform hosts a number of individual applications within the ecosystem. The user can use the application switcher to navigate between applications, and the platform provides common services such as user authentication, device configuration and user preferences.
Many of these applications are built in to the platform (Print Beat, Media Locator, Resource Manager, etc.) This API provides mechanisms for other applications to integrate into PrintOS, appear in the marketplace and app switcher and access user and organization data.
Services
PrintOS is a micro-services architecture. The platform and its applications are made up of over 100 individual services, each running in its own container and deployed on clusters of servers. Multiple instances of each service are running simultaneously for redundancy and to scale with demand.
Each service has its own login that it can use to obtain a service session to make calls to other services. For interactive calls, when a user originates the chain of calls, the user's session can be used to call through to other services to perform operations on the users' behalf. But for some high-privilege operations and for background tasks that occur when the user is not active, the service can use its own session to make the call.
Services require specific permission grants to be able to make these non-user calls, and these grants are made sparingly to minimize security risks. One common example is authorize/links call that services must make to determine user permissions.
Development Environment (Stacks)
In PrintOS parlance, a "stack" is a complete deployed instance of the PrintOS platform, complete with all services, applications, devices, organizations and users. Each stack has its own web hosting, CDNs, databases, caches, streams, queues, topics, buckets and other resources. We have a single production stack that serves all of our customers worldwide, and we also maintain a set of other stacks that are used internally for various development and testing activities.
Partner applications typically need to integrate with a few of these stacks. Each stack usually requires a separate deployed instance of the application, configured to participate in that stack. We expect application partners to support at least these stacks:
- Production - https://www.printos.com - Used by all customers, worldwide. Updated every two weeks, with additional patches as needed to address customer issues.
- Daily - https://daily.gsbprint.net - Used by developers to run the latest code. Updated continuously. All new code committed to our repositories is automatically built, tested and then deployed to the daily stack. We have developers around the world, so updates occur around the clock, 7 days a week.
- Stage - https://stg.printopt.org - Used for final qualification prior to deployment to production. At the end of every two-week development cycle, new code is deployed here for one week of final testing before it goes to production.
User Authentication
PrintOS uses HP ID, the Unified Identity Management Ecosystem for all of HP, including PrintOS. When a user arrives at an integrated application without a valid user session, the application will need to perform an OAUTH2 login using HP ID and then present the resulting token to PrintOS to obtain a PrintOS user session.
Getting Started with HP ID
To use HP ID, you first need to register as an HP Developer and request access to the API:
- Go to http://hp.io and register as an HP developer (if you have not already done so)
- Once you complete the registration process, log in to hp.io and havigate to https://developers.hp.com/hp-id-enrollment to actually complete the enrollment.
- Please include jon.lewis@hp.com and benny.shimshoni@hp.com in the HP Contact field and enter "PrintOS 3rd party applications" for the Project Using HP ID field.
- This results in an email being sent to the HP ID registration desk. Your registration will need to be confirmed.
Notes on HP ID sessions
When the user logs in to PrintOS, we create a PrintOS user session token. As long as the user keeps using PrintOS, this session will endure and the user doesn't have to log in with HP ID every time. In the same way, partner application session may persist in the browser for some specified period of time so the user doesn't have to log in every time they use the application.
HP ID also manages a single-sign-on session that is typically good for eight hours. This means that if the user logs in to PrintOS (using HP ID), in addition to the PrintOS session, and HP ID session is also created. If the user then navigates to a partner application and clicks to log in, HP ID will short-circuit and will log the user in using their existing HP ID session and will not prompt for a username or password. (A consent dialog may still be presented.)
If the user logs out of either the partner app or PrintOS, the HP ID session is removed and the user will have to provide a username and password to log in again.
Application Header Bar
All PrintOS applications use a common header that reflects the PrintOS brand, the title of the application and provides common navigation elements. The PrintOS team provides a simplified version of this top bar that is required in all partner applications:
The top bar is encapsulated in a JavaScrip loader and is hosted in a PrintOS CDN. The application includes it using a <script> tag and provides basic information to the header, such as the application name and the location of the corresponding PrintOS stack.
Header documentation can be found here: Partner Application Header Bar
User Transfer Query Parameters
When a user selects a partner application in the app switcher and navigates to it, PrintOS will automatically add query parameters to the URL:
- userId - The ID (UUID) of the current logged-in user
- orgId - The ID (UUID) of the current active user context.
The partner application should handle these query parameters to try to keep the user and context ID in sync if possible:
- If the logged-in user ID matches, but the organization does not, switch to the specified organization.
- If the logged-in user ID does not match, log out the user.
- If there is no active session, retain the parameters through the login (store in state)
- After login, if the user ID matches, but the organization does not, switch to the specified organization.
Note that #3 requires special handling. The user ID must be passed through so the org switch is only done if the user ID matches, but the user should not be automatically logged out if the user ID does not match after login.
When navigating back to PrintOS, the link in the header automatically adds the user and org parameters supplied by the app to the URL and PrintOS implements similar logic.
When a single user is using PrintOS, the normal cases will be #3 (the first time) and #1 (thereafter). In a shared- terminal environment, #2 becomes more likely. This isn't a security mechanism, but rather a convenience to prevent confusion.
Typical Interaction Sequences
The following sequence diagrams show typical interactions between a third-party application and PrintOS. These diagrams show the following entities:
- Browser - The user's browser, used to interact with PrintOS and the integrated application
- App Service - The back-end hosted service for the third-party application. This service provides APIs used by the app's client code.
- HPID - HP's OAUTH2 identity provider
- AAA - PrintOS service providing user, organization and permission information
- Enforcer - PrintOS service providing information about applications and features purchased in the marketplace
- Portal - PrintOS service providing user preference and other information related to client UI
Service Login
To interact with AAA and other parts of the PrintOS platform, the application needs a service session. Each service is assigned a login/password that it can use to log in and obtain this session. The session is then used to call APIs in the platform as the service.
Service sessions have a limited lifetime (usually 24 hours). The data returned from the login API indicates when the session will expire. The service should log in again and obtain a new session sometime in the last hour before expiration. AAA authorizecalls will return HTTP error code 412 if the service session is expired.
The service must not log in every time it wants to make an API call. It should cache the service session and continue using it until it expires or is nearing expiration.
Most PrintOS services are horizontally scaled, meaning there are multiple instances of the service running at any given time. We recommend having each instance of the service log in and maintain its own unique service session in memory. There is no need to synchronize service sessions across multiple service instances.
Service login credentials are rotated periodically.
User Login
When the user first arrives at the application, he or she will not have a valid user session. The application must log the user in using HPID (OAUTH2) and then use the resulting access token to obtain a PrintOS user session. This user session may then be tracked as the application sees fit.
The above sequence diagram shows a typical login sequence:
- The user clicks on a sign-in button in the application.
- The application POSTS back to its service to request a OAUTH2 sign-in link, passing a few parameters:
- The operation (login)
- The URL to redirect to after the login
- The service stores the parameters using a unique state ID. It then builds and returns an HP ID URL with:
- Login parameters
- State ID
- A callback URL
- The browser redirects to the HP ID OAUTH2 login UI and the user logs in.
- After login, HP ID redirects the user back to the callback, with a code and the state ID.
- The callback uses the state ID to retrieve the login paremeters.
- The callback exchanges the code for an HP ID access token, and then uses the access token to get a PrintOS user session from AAA.
- (Optional) The callback may also check user permissions and entitlements before creating a session.
- The callback creates an app session (or just uses the PrintOS user session) and returns it in a cookie.
We recommend storing the user session in a secure, HTTPS-only cookie on the application domain. Other implementations are possible, including storing the PrintOS user session server-side and associating it with an application-specific session or using other technologies such as JWT.
Note that the user's permissions and the current organization's application list need to be fetched initially to determine the type of user (User, Admin, ReadOnly) and whether the current organization has purchased the application. This information may then be cached so it doesn't have to be fetched on every single user call to the application's service. The cache time should be chosen to meet performance goals while responding reasonably to user role changes and subscription expiration.
User Logout
The user logout sequence uses the same flow through HP ID, getting a redirect URL, redirecting the browser, and then accepting the response on a callback, except that the specified operation is a logout instead of login. The logout sequence redirects the browser a couple of times but shows no UI to the user. It is necessary to route the logout through HP ID so the HP ID single-sign-on session can be removed from the browser.
Organization Context Switching
In PrintOS, a user may be a member of multiple organizations. Sometimes one PrintOS customer will create multiple organizations to manage their business needs. An individual user may also be invited to multiple organizations owned by different businesses. This might be the case for an independent contractor.
While a user can have membership in multiple organizations, a logged-in session may operate in only one organization context at a time. PrintOS provides APIs to list the user's possible contexts and to switch between contexts.
The current context can be verified at any time by calling validateUserToken(). This call checks if the user token is currently valid and returns the current context for that session. You may also get a list of all of the possible contexts for the user by calling getUsersContexts().
When switching contexts, the call to loginContext() will return a new user session ID associated with the new organization context. This new session will need to be stored in the application session or browser cookie for the context switch to take effect. The old session will continue to be associated with the previous organization context until it expires.
User Preferences
In PrintOS, each user has the ability to set user preferences, such as their preferred localization language (locale), measurement units and time zone. These settings are managed in the main PrintOS UI. Applications may fetch this information from the portal service using the user's session.
SDK access to preferences data is read-only. Note that additional information may be present, including table layout and account setup state variables. The application should ignore any data it doesn't recognize.
Marketplace Integration
Once a partner application is ready to be offered to customers, the PrintOS core team will list it in the PrintOS marketplace. We will need graphical assets and copy to describe the application.
More details coming soon...
Example Application
An example PrintOS partner application is available that demonstrates the APIs and concepts in this document
- Java/RestEasy/Spring Application Service with AngularJS/HTML/CSS Application UI: Download code sample
PrintOS APIs
Endpoints
Each PrintOS stack has a different API endpoint. The endpoints for the three partner integration stacks are:
| Stack | Endpoint URL |
|---|---|
| Daily | https://dev.printos.api.hp.com/platform/ |
| Stage | https://stage.printos.api.hp.com/platform/ |
| Production | https://printos.api.hp.com/platform/ |
For example, the AAA authorize endpoint on daily is:
https://dev.printos.api.hp.com/platform/api/aaa/v4/authorize
and on production, it's:
https://printos.api.hp.com/platform/api/aaa/v4/authorize