Frequently-asked questions

Read on for answers to questions about FREEPCIS.

General questions about FREEPCIS

What is FREEPCIS?

FREEPCIS is a free EPCIS repository for development and test.

What is Electronic Product Code Information Services (EPCIS)?

Electronic Product Code Information Services (EPCIS) is a GS1 Standard for visibility data. EPCIS data consists of events, where each event is a record of something that happened in the real world. EPCIS data is used to track and trace products, assets, documents, and other things as they move through a business process, especially a business process that spans multiple physical locations and multiple organizations. An EPCIS event records what was involved in a business process step, when the step took place, where it took place, and additional business context that answers the question “why.”

What is an EPCIS repository?

An EPCIS repository is a service that lets you capture EPCIS event data, and then later query for events that match specified query criteria. It's basically a database designed especially for EPCIS data, with web service interfaces for capturing and querying data as specified by the EPCIS standard.

Why does FREEPCIS exist?

To make it easier to get started with EPCIS. If you are building a visibility data system, testing EPCIS software, or just trying to experiment and learn, FREEPCIS is an EPCIS repository that you can set up in a minute or two and start using right away.

Why is FREEPCIS free?

We offer FREEPCIS free of charge to make it easy for everybody to start using EPCIS. We think you should be able to experiment and learn without investing a lot of time or money.

So what's the catch?

FREEPCIS is limited to storing no more than 25 EPCIS events. This is enough for development and test, and even for small pilots, but probably not sufficient for a production deployment. When you are ready to start using EPCIS in production, you are ready to graduate to a commercial EPCIS repository that has no such limit.

Any other limitations?

Not many. You are limited to no more than 10 standing queries (subscriptions). That's probably more than you are likely to need, anyway. A standing query is automatically suspended after it's executed 100 times, so you can't accidentally leave one running forever. And the activity log does not keep activity records more than two weeks old.

That's all?

Yup. Apart from those limits, FREEPCIS is a complete implementation of the EPCIS 1.2 standard.

Getting started

FREEPCIS sounds great. How do I get started?

Getting started is as easy as 1, 2, 3! Step 1: Register for a free account. Step 2: Choose your server name and other settings. Step 3: That's it! You're ready to start capturing and querying EPCIS events.

Why do I have to register for an account?

FREEPCIS stores EPCIS data that you capture so you can query for it later. You need to have an account so that nobody but you can access your data.

What information do I need to provide to register?

Just your name, e-mail, company name, and your time zone.

Why do you need that information?

You use your e-mail to log in, so we need to know that to recognize you. We want your name so that we can greet you when you log in. We need to know your time zone so that we can display dates and times. And we want your company name so that we have an idea of what sorts of companies are interested in FREEPCIS (but we won't mind if you leave that one blank).

Will I be asked to provide a credit card number?

No. FREEPCIS is free, so we don't need your credit card number.

How will you use my e-mail address?

Right after you register, we will send you an e-mail to complete your registration. You click the link in the e-mail, which takes you to a screen where you set your password, and then your account is ready to use. After that, you enter your e-mail address and password to log in. If you ever forget your password or want to change it, we will send you another e-mail with a reset password link. If you provide feedback or ask a question through the Feedback link, we might use your e-mail to send you a reply. Finally, we may occasionally use your e-mail to notify you of new features or other changes to FREEPCIS.

One thing we will not do is give your e-mail address to anybody else, for any reason.

I forgot my password; what do I do?

Just click the Forgot Password link on the home page or login screen. We will send you an e-mail with a link to reset your password.

What if I remember my password but I want to change it?

Use the Forgot Password link on the home page or login screen (even though you didn't really forget it). We will send you an e-mail with a link to reset your password.

How can I change the e-mail address for my account?

Click the Feedback link and ask for a change. We'll take care of it as soon as possible.

Questions about account settings

You said Step 2 of getting started is to choose my settings. What settings to I have to choose?

Three things:

  1. Your server name.
  2. Security settings for your server.
  3. What to do if you exceed the limit of 25 events.

What is the server name setting?

The server name is a name you choose to identify your EPCIS repository. It has to be different from the name chosen by any other FREEPCIS user — it's how we recognize that incoming EPCIS events and queries are aimed at your server and not somebody else's. Your server name becomes part of the capture and query URLs that EPCIS capturing applications and EPCIS querying applications use to communicate with your server.

Why don't you just use my e-mail address as the server name?

You may have to give your capture and query URLs to other people whom you want to communicate with your EPCIS server, but you might not want them to know what e-mail address you used to set up your account. Also, it allows you to change your e-mail address without having to change your capture and query URLs.

How does the server name become part of the capture and query URLs?

Like this. Suppose you've chosen MyServer as your server name. Then your capture and query URLs would be:

The settings page will show you a preview of the URLs so you can see how they look before you commit.

Are there any restrictions on my server name?

It can only contain letters, digits, and the hyphen (-) character. This is so that it will work as part of a URL. You probably will want it to be easy to remember, and reasonably short. Other than that, go wild!

What are the security settings?

You can choose to protect your capture and query URLs with a username and password. If you select this option, your EPCIS capturing application or EPCIS querying application will have to provide the username and password you select using HTTP Basic Authentication. This provides an extra layer of protection.

If you don't select this option, then anybody who knows your capture or query URLs will be able to capture events or issue queries. Because your server name might not be that hard to guess, this is definitely not recommended. However, if your capturing application or querying application is having trouble connecting with FREEPCIS, it is sometimes helpful to turn off security temporarily if you think that might be causing the problem.

What about the event limit setting?

Your FREEPCIS server is limited to store no more than 25 events. If you send an EPCIS document to the capture URL that contains more than 25 events, it will be rejected.

The question is: what happens if you send a document containing 25 or fewer events, but when added to the events you already have stored you would be over the limit? You have a choice:

For example, suppose you already have 20 events stored in your repository. You then try to send an EPCIS document containing 10 new events to your capture URL. 10 plus 20 is greater than 25, so this would put you over the limit. If you choose the first option, the 10 new events will be rejected and your repository will still hold the previous 20 events. If you choose the second option, five or more of the old events will be removed and the 10 new events will be captured, leaving a total of 25 or fewer events in your repository.

When FREEPCIS automatically deletes previously captured events, it will never break up a set of events that were captured at the same time. This means it might have to delete more events than would otherwise be necessary to meet the limit. In the previous example, suppose the 20 existing events had been captured in two groups of 10 events. To make room for the 10 new events, FREEPCIS will delete all 10 of the events captured in one of the previous capture operations, even though only five events were needed to make room.

Questions about capturing EPCIS events

How do I capture EPCIS events?

To capture EPCIS events, you send an EPCIS document containing one or more events to your capture URL, using HTTP POST. Typically this is done by software called an "EPCIS Capturing Application".

What do you mean by an "EPCIS Document"?

An EPCIS document is an XML file containing EPCIS events, formatted according to the XML schema specified in the EPCIS 1.2 standard. It's called an EPCIS document because the root element of the XML is <epcis:EPCISDocument>.

How do I create an EPCIS document?

It's possible to create an EPCIS document by typing the XML by hand. You can follow the examples given in the EPCIS 1.2 standard. Or you could use an XML editor. If you're not a programmer who is familiar with XML, however, these methods might not be for you.

A more convenient way is to use the Visibility Data Workbench. This is a free tool in which you can create EPCIS events by filling in forms.

In a working visibility system, EPCIS documents are created by EPCIS Capturing Applications. If you are writing an EPCIS Capturing Application, the programming language you're using will probably provide a way to create XML documents using the XML schema provided by the EPCIS 1.2 standard, and also a way to deliver it to your EPCIS server using HTTP POST.

What if I don't have an EPCIS Capturing Application?

If you just have an EPCIS document but no EPCIS Capturing Application, you can use a command-line tool like cURL. For example, here is how you would capture an EPCIS document you have in a file:

curl --data-binary @myfile.xml http://www.freepcis.com/server/MyServer/capture

Of course, you would substitute the actual filename in place of myfile.xml, and your chosen server name in place of MyServer.

If you have configured a username and password for your capture interface (and you should — see Questions About Account Settings, above) then the command looks like this:

curl --user username:password --data-binary @myfile.xml http://www.freepcis.com/server/MyServer/capture

You can also use the Visibility Data Workbench to send an EPCIS document to any EPCIS server, including FREEPCIS.

I just tried to capture some events. How do I know it worked?

Check the Events page (from the main menu bar). You should see your events listed there. You can also check the Activity Log page. You should see your capture operation listed there, and it will also indicate if it was successful or if there were errors.

My capture operation failed because I am over the limit of 25 events. What do I do?

You can go to the Events page (from the main menu bar) and delete events to make room. You can delete all events by checking the box in the upper left corner and then selecting "Delete" from the "Bulk Action" menu.

If you are trying to capture more than 25 events at a time, however, then you are out of luck. You need to graduate to a commercial EPCIS repository.

Questions about querying for EPCIS events

How do I query for EPCIS events?

To capture EPCIS events, you send a query request to the EPCIS query interface. Typically this is done by software called an "EPCIS Accessing Application".

What do you mean by a "query request"?

The EPCIS standard defines seven different operations that an EPCIS Accessing Application can perform on an EPCIS server. For each operation, there is a request message that says what you want to do, and a response message that tells you the result. You send the request message to your EPCIS query URL using HTTP POST, and the HTTP response contains the response message. An EPCIS query is formatted in XML as a SOAP message.

What are the operations I can request using the query interface?

The most common request is called Poll, which is a request to retrieve EPCIS events that match criteria you specify in your request. The response to a Poll request is a list containing the matching events (if any).

What other operations are there?

There are three operations for managing standing queries (subscriptions): Subscribe, Unsubscribe, and getSubscriptionIDs. The getQueryNames operation tells you which types of queries are supported by the EPCIS server (in the case of FREEPCIS, the answer is that it supports SimpleEventQuery. And finally, the GetStandardVersion and GetVendorVersion operations tell you what version of the EPCIS standard the server supports (1.2 in the case of FREEPCIS) and what version of any vendor-specific extensions are supported (none in the case of FREEPCIS). These last two operations are often used as a quick way to confirm communication with an EPCIS server.

How do I create an EPCIS Poll query request?

It's possible to create a Poll request by typing the XML by hand, or you could use an XML editor. If you're not a programmer who is familiar with XML, however, these methods might not be for you.

A more convenient way is to use the Visibility Data Workbench. This is a free tool in which you can create EPCIS Poll queries by filling in forms.

In a working visibility system, EPCIS documents are created by EPCIS Accessing Applications. If you are writing an EPCIS Accessing Application, the programming language you're using will probably provide a way to create SOAP queries using the XML schema and WSDL schema provided by the EPCIS 1.2 standard, and also a way to deliver it to your EPCIS server using HTTP POST.

What if I don't have an EPCIS Accessing Application?

If you just have an EPCIS query formatted as a SOAP message but no EPCIS Accessing Application, you can use a command-line tool like cURL. For example, here is how you would issue a query you have in a file:

curl --data-binary @myquery.xml http://www.freepcis.com/server/MyServer/query

Of course, you would substitute the actual filename in place of myquery.xml, and your chosen server name in place of MyServer. The output of cURL will be the response to your query.

If you have configured a username and password for your capture interface (and you should — see Questions About Account Settings, above) then the command looks like this:

curl --user username:password --data-binary @myquery.xml http://www.freepcis.com/server/MyServer/query

You can also use the Visibility Data Workbench to send an EPCIS query request to any EPCIS server, including FREEPCIS.

I just tried to issue a query. How do I know it worked?

The response message returned by HTTP contains the results of your query. You can also check the Activity Log page. You should see your query operation listed there, and it will also indicate if it was successful or if there were errors.

Questions about standing queries (subscriptions)

What is a standing query?

A standing query is a query that is automatically run on a recurring schedule. Any new events that match the query criteria are automatically sent to a specific URL. When you set up the standing query, you specify the query criteria (just like in a Poll request), the schedule, and the URL to which results are sent. You can also say whether a message should be sent only when there are new events that match the query, or every time the query is run (in which case a message might be sent containing no events).

What is a subscription?

Just another name for a standing query. The EPCIS standard calls it a standing query, but since the operation that sets up a standing query is called Subscribe a standing query is also sometimes called a subscription.

How do I create a standing query?

A standing query may be created using any of the methods described above for Poll queries, except that the request you create will be a Subscribe request instead of Poll.

How does a Subscribe request differ from Poll?

Like Poll, a Subscribe request includes query criteria that says what events you want your query to match. In addition, a Subscribe request has these additional parameters:

See the EPCIS standard, Sections 8.2.5 and 11.1, for more details.

I just tried to create a standing query. How do I know it worked?

The response message returned by HTTP contains an acknowledgement if everything worked as planned, or an error message. You can also check the Activity Log page. You should see your subscribe operation listed there, and it will also indicate if it was successful or if there were errors.

After that, each time the schedule is met you'll see a new entry on the Activity Log page saying that the query executed. This will tell you how many new events matched the query criteria, whether a results message was sent, and if the delivery of the results message was successful.

How can I see all my standing queries?

Check the Subscriptions page. This will show you all standing queries, their schedules, and when they next will be run.

What does "queries before expire" mean?

A limitation of FREEPCIS is that a standing query is run no more than 100 times. After that, it "expires", meaning that it still shows up in the listing but will no longer be run. The "queries before expire" column on the Subscriptions page tells you how many more times the query will be run before it expires.

What do I do after my standing query expires?

You don't have to do anything. However, if you want to remove it, you can send an Unsubscribe request to the EPCIS query interface, or you can simply use the Subscriptions page to delete the standing query.

Can I remove a standing query before it expires?

Of course. Send an Unsubscribe request to the EPCIS query interface, or simply use the Subscriptions page to delete the standing query.