# Global actions 

This page documents all the root level mutations powered by [Global actions](https://docs.forgelivo.com/guides/actions/types-of-actions#global-actions) in the **openai-screenwriter-tutorial-v2** API.

### Action Result format 

Each API action returns results in the same format that includes a success indicator, errors, and the actual result if the action succeeded. The result is the record that was acted on for a model action, or a list of records for a bulk action, or a JSON blob for Global Actions. Model actions that delete the record don't return the record.

The `success` field returns a boolean indicating if the action executed as expected. Any execution errors are returned in the `errors` object, which will always be `null` if `success` is true or contain `ExecutionError` objects if `success` is false.

`ExecutionError` objects always have a `message` describing what error prevented the action from succeeding, as well as a `code` attribute that gives a stable, searchable, human-readable error class code for referencing this specific error. Details on each error code can be found in the [Errors](https://docs.forgelivo.com/api/openai-screenwriter-tutorial-v2/development/errors) documentation. All `ExecutionError` object types returned by the GraphQL object can be one of many types of error, where some types have extra data that is useful for remedying the error. All error types will always have `message` and `code` properties, but some, like `InvalidRecordError` have extra fields for use by clients.

### Errors when using the generated client 

The generated JavaScript client automatically interprets errors from invoking actions and throws JavaScript `Error` instances if the action didn't succeed. The `Error` objects it throws are rich, and expose extra error properties beyond just `message` and `code` if they exist.

Errors thrown by the JavaScript client are easiest to catch by using a `try/catch` statement around an `await`, like so:

```typescript
import {
  GadgetOperationError,
  InvalidRecordError,
} from "@gadgetinc/api-client-core";

// must be in an async function to use await` syntax
export async function run({ api }) {
  try {
    return await api.exampleModel.create({ name: "example record name" });
  } catch (error) {
    if (error instanceof GadgetOperationError) {
      // a recognized general error has occurred, retry the operation or inspect \error.code\`
      console.error(error);
    } else if (error instanceof InvalidRecordError) {
      // the submitted input data for the action was invalid, inspect the invalid fields which \`InvalidRecordError\` exposes
      console.error(error.validationErrors);
    } else {
      // an unrecognized error occurred like an HTTP connection interrupted error or a syntax error. Re-throw it because it's not clear what to do to fix it
      throw error;
    }
  }
}
```

For more information on error codes, consult the [Errors](https://docs.forgelivo.com/api/openai-screenwriter-tutorial-v2/development/errors) documentation.

### ingestData 

```typescript
const result = await api.ingestData();
```

```tsx
const ExampleRunIngestDataComponent = () => {
  const [{ data, error, fetching }, ingestData] = useGlobalAction(api.ingestData);

  return (
    <>
      <button
        onClick={async () => {
          await ingestData();
        }}
      >
        Run Action
      </button>
      Result: {JSON.stringify(data)}
    </>
  );
};
```

```graphql
mutation IngestData {
  ingestData {
    success
    errors {
      message
    }
    result
  }
}
```

##### Output 

ingestData returns whatever data the effects within it produce.

```graphql
type IngestDataResult {
  success: Boolean!
  errors: [ExecutionError!]
  result: JSON
}
```

### findSimilarMovies 

##### Input 

findSimilarMovies accepts the following input parameters

```typescript
export type FindSimilarMoviesArguments = {
  quote?: (Scalars["String"] | null) | null;
};
```

```graphql
input FindSimilarMoviesArguments {
  quote: String
}
```

```typescript
const result = await api.findSimilarMovies({
  quote: "example value for quote",
});
```

```tsx
const ExampleRunFindSimilarMoviesComponent = () => {
  const [{ data, error, fetching }, findSimilarMovies] = useGlobalAction(api.findSimilarMovies);

  return (
    <>
      <button
        onClick={async () => {
          await findSimilarMovies({
            quote: "example value for quote",
          });
        }}
      >
        Run Action
      </button>
      Result: {JSON.stringify(data)}
    </>
  );
};
```

```graphql
mutation FindSimilarMovies($quote: String) {
  findSimilarMovies(quote: $quote) {
    success
    errors {
      message
    }
    result
  }
}
```

##### Output 

findSimilarMovies returns whatever data the effects within it produce.

```graphql
type FindSimilarMoviesResult {
  success: Boolean!
  errors: [ExecutionError!]
  result: JSON
}
```

## Returning data 

You can use a `return` statement to return data from a global action call.

```typescript
export const run: ActionRun = async ({ api, logger }) => {
  return "Hello, World";
};
```