These functions read the context your app was opened in — the current card, the current pipe, its fields, and the user's locale settings. They need no arguments: the client already knows where it was mounted.

For anything outside the current context, use p.query() against the GraphQL API.

Every function on the client is asynchronous. Your app runs in an iframe, so each call crosses the frame boundary and hands back a promise — even for values Pipefy already knows. The only synchronous things here are the plain properties: p.locale and the context properties.

Card data

p.card()

Returns a Promise resolving to the card your app was opened on.

p.card() takes no arguments. To read a different card, query it by ID with p.query().

⚠️

Resolves to null when there is no card

On a surface with no card in context — a pipe button, a pipe view — p.card() still returns a promise, but it resolves to null. Check the resolved value before reading from it:

JavaScript

p.card().then(function (card) {
  if (!card) return;
  render(card);
});

p.pipe() behaves the same way.

Example call

p.card().then(function (card) {
  console.log(card.title); // "Hotdog App"
});

Return

{
  "id": "Vtp5gHjo",
  "title": "Hotdog App",
  "assignees": [
    {
      "name": "Jim Yang",
      "username": "jim_yang",
      "avatar_url": "https://gravatar.com/avatar/5e071a20cf0898300c"
    }
  ],
  "labels": [
    { "id": 2334, "name": "High", "color": "#CCCCCC" }
  ],
  "current_phase": {
    "id": 1357961,
    "name": "Doing",
    "description": "Show time!",
    "done": false
  },
  "field_values": {
    "start_date": "2017-02-19T01:58:08+00:00",
    "approved": false
  }
}

⚠️

field_values is an object, not an array

It is keyed by field ID, so read a value with card.field_values['start_date'] — not by index. Earlier versions of this page showed an array; that was wrong.

These six keys — id, title, assignees, labels, current_phase, field_values — are the ones you can rely on everywhere. Depending on which surface rendered your app you may also see extra keys such as due_date, pipe_id or child_cards. Do not build against those: they are not present on every surface, and code that reads them works in a card badge and returns undefined in a card tab. If you need a field that is not in the list above, query it explicitly with p.query().

Handling failures

If the underlying query fails — an expired session, a deleted card, a network error — the promise does not reject. The error is logged to the console and the promise resolves to null. So a .catch() will not fire on a query failure; you have to check the resolved value:

p.card().then(function (card) {
  if (!card) {
    // No card in context, or the query failed, or the card is no longer readable.
    // Check the browser console for the underlying error.
    p.showNotification('Could not load this card', 'error');
    return;
  }
  render(card);
});

p.fields() and p.pipe() swallow errors the same way. This means a null result is ambiguous — it can mean "nothing here" or "the request failed" — and the console is the only place the distinction shows up.

p.cardAttachments()

Returns a Promise resolving to the links your app attached to the current card with p.attach(). Attachments belonging to other apps are not included.

Each object contains id, url and name.

p.cardAttachments().then(function (attachments) {
  console.log(attachments);
  // [{ id: "LPpssdkK", url: "https://emojipedia.org/shrug/", name: "Shrug 🤷" }]
});

Use the id to remove one again with p.detach().

Pipe data

p.pipe()

Returns a Promise resolving to the current pipe. Like p.card(), it resolves to null when there is no pipe in context or the query fails — and it can also resolve to null for a pipe that has no cards yet, so treat an empty pipe as a case your app has to handle.

Return

{
  "id": "-Pclaixx",
  "name": "Sprint Planning",
  "organization_name": "Pied Piper",
  "cards_count": 4
}

These four keys are the ones you can rely on everywhere. As with p.card(), some surfaces hand back extra keys — don't build against them, and use p.query() for anything else you need about the pipe.

p.fields()

Returns a Promise resolving to every field defined on the current pipe, across all phases and the start form.

Example call

p.fields().then(function (fields) {
  console.log(fields); // [{ id: "title", ... }]
});

Return

[
  {
    "id": "follow_the_steps_below_before_moving_the_card_forward",
    "label": "Follow the steps below before moving the card forward:",
    "description": "If you're not sure what to do here, click the \"?\" icon to learn more.",
    "phase": { "id": 1357961, "name": "Empathize", "done": false, "start_form": true },
    "required": false,
    "type": "Statement"
  }
]

The id values here are the same keys used in a card's field_values object, so the two are designed to be read together:

Promise.all([p.card(), p.fields()]).then(function (results) {
  var card = results[0];
  var fields = results[1];

  if (!card || !fields) return;

  fields.forEach(function (field) {
    console.log(field.label, '=', card.field_values[field.id]);
  });
});

User and environment

p.locale

The current user's locale, as a plain property — not a function, and not a promise. Pipefy passes it to your iframe when the app loads, so it is available synchronously.

Possible values include en, en-gb, pt-br, es, fr and ru.

var locale = p.locale;
console.log(locale); // "pt-br"

p.timezone()

Returns a Promise resolving to the current user's timezone, as a tz database name.

p.timezone().then(function (timezone) {
  console.log(timezone); // "America/Los_Angeles"
});

⚠️

Can resolve to undefined

The timezone comes from a global Pipefy only sets for signed-in users. Where that global is absent, p.timezone() resolves to undefined rather than rejecting. Provide a fallback:

JavaScript

p.timezone().then(function (timezone) {
  var tz = timezone || 'UTC';
});

Context properties

Alongside p.locale, the client carries a few identifiers for the context it was opened in. Like p.locale, these are plain properties, available synchronously:

⚠️

Use p.app.pipeId in GraphQL queries

p.pipeId and p.cardId do not consistently carry the numeric IDs the GraphQL API expects — on some surfaces they hold short IDs instead. For API calls, use p.app.pipeId. See the variables example on that page.

See also

• Make API calls — read anything not covered here, via GraphQL
• Custom App Data — store your own data, and attach links to cards
• Promises — how async results are returned