npm package: @jondoesflow/copilot-studio-action-mapper
Description: Test and manage Custom APIs/Actions for Copilot Studio integration. Generate schemas, test actions with sample inputs, and validate responses for AI consumption.
Author: JonDoesFlow
Latest version: 1.0.6

# Copilot Studio Action Mapper

A Power Platform Toolbox tool that simplifies testing and integrating Custom APIs from Dataverse into Microsoft Copilot Studio.

## What Does This Tool Do?

The Copilot Studio Action Mapper helps you bridge the gap between Dataverse Custom APIs and Microsoft Copilot Studio by:

1. **Browsing Custom APIs**: Displays all Custom APIs in your Dataverse environment in an easy-to-navigate interface
2. **Testing Actions**: Executes Custom APIs with sample inputs and shows real-time JSON responses
3. **Generating OpenAPI Schemas**: Auto-generates OpenAPI 2.0 (Swagger) specifications that Copilot Studio requires for REST API actions
4. **Validating Responses**: Ensures your API responses are properly formatted for AI consumption
5. **Exporting Documentation**: Creates comprehensive JSON documentation for team collaboration

## Why Use This Tool?

### Save Time
- **No Manual Schema Writing**: Automatically generates the exact OpenAPI 2.0 format that Copilot Studio expects
- **Instant Testing**: Test your Custom APIs without writing code or using Postman
- **One-Click Export**: Copy schemas directly to clipboard for immediate use in Copilot Studio

### Reduce Errors
- **Correct Format Guaranteed**: Generates valid OpenAPI 2.0 Swagger specifications every time
- **Type Mapping**: Automatically maps Dataverse data types to Swagger types
- **Validation Before Integration**: Test APIs before connecting them to your copilots

### Improve Collaboration
- **Visual API Browser**: See all your Custom APIs at a glance
- **Documentation Export**: Share API specifications with your team
- **Clear Parameter Display**: View input requirements and output properties before testing

## Official Documentation

For more information about using Custom APIs with Copilot Studio:

- **[Create REST API Copilot Connectors in Copilot Studio](https://learn.microsoft.com/en-us/power-platform/release-plan/2024wave2/microsoft-copilot-studio/create-rest-api-copilot-connectors-copilot-studio)** - Official Microsoft documentation on REST API integration
- **[Custom API Documentation](https://learn.microsoft.com/en-us/power-apps/developer/data-platform/custom-api)** - Learn how to create and use Custom APIs in Dataverse
- **[Copilot Studio Actions](https://learn.microsoft.com/en-us/microsoft-copilot-studio/advanced-plugin-actions)** - Understanding actions in Copilot Studio

## 📖 Usage

### 1. Connect to Environment

- Open Power Platform Toolbox
- Connect to your Dataverse environment
- Launch "Copilot Studio Action Mapper"

### 2. Browse Custom APIs

- All Custom APIs will load automatically in the left sidebar
- Use the search box to filter by name or description
- 🔵 Function APIs are marked with a blue icon
- ⚡ Action APIs are marked with a lightning icon

### 3. Test an Action

1. **Select an API** from the list
2. **Review the parameters** in the "Input Parameters" section
3. **Enter test values** in the "Test Action" section
4. **Click "Execute Action"** to run the test
5. **View the response** in JSON format

### 4. Generate Copilot Schema

1. Select a Custom API
2. Click **"Generate Copilot Schema"** button
3. Copy the generated schema
4. Use it in Copilot Studio when configuring actions

### 5. Export Documentation

1. Select a Custom API
2. Click **"Export Documentation"** button
3. Save the JSON file with complete API documentation

## 🎯 Use Cases

### For Copilot Studio Developers

- **Test Custom APIs** before integrating them into Copilot Studio
- **Generate schemas** to streamline Copilot configuration
- **Validate responses** to ensure AI-friendly formats
- **Document actions** for team collaboration

### For Power Platform Developers

- **Debug Custom APIs** by testing with different inputs
- **Verify parameter types** and requirements
- **Understand API structure** through visual representation
- **Share API specifications** with stakeholders

## 🔧 Technical Details

### Custom API Types Supported

- **Actions**: Standard actions that modify data or trigger processes
- **Functions**: Read-only functions that return data
- **Bound APIs**: APIs bound to specific entities
- **Unbound APIs**: Global APIs not tied to entities

### Parameter Types

The tool supports all Dataverse parameter types:
- Boolean
- DateTime
- Decimal
- Entity
- EntityCollection
- EntityReference
- Float
- Integer
- Money
- Picklist
- String
- StringArray
- Guid

### Generated Schema Format

The tool generates **OpenAPI 2.0 (Swagger)** specifications that Copilot Studio requires for REST API actions:

```json
{
  "swagger": "2.0",
  "info": {
    "title": "API Display Name",
    "description": "API Description",
    "version": "1.0.0"
  },
  "paths": {
    "/api_name": {
      "post": {
        "operationId": "api_uniquename",
        "summary": "API Display Name",
        "parameters": [...],
        "responses": {
          "200": {
            "description": "Success",
            "schema": {
              "type": "object",
              "properties": {...}
            }
          }
        }
      }
    }
  },
  "securityDefinitions": {
    "oauth2": {...}
  }
}
```

This format is directly compatible with Copilot Studio's REST API connector requirements.

## 🛠️ Development

### Project Structure

```
copilot-studio-action-mapper/
├── src/
│   └── app.ts          # Main TypeScript application
├── index.html          # UI layout
├── styles.css          # Styling
├── package.json        # Package configuration
├── tsconfig.json       # TypeScript configuration
└── README.md           # Documentation
```

### Key Technologies

- **TypeScript**: Type-safe development
- **PPTB APIs**: 
  - `toolboxAPI`: Connection, notifications, clipboard
  - `dataverseAPI`: FetchXML, action execution
- **Modern CSS**: Responsive, accessible design

## 📝 Known Limitations

1. **Bound API Testing**: Requires a record ID (currently shows TODO_RECORD_ID)
2. **Complex Types**: Entity and EntityCollection inputs need JSON format
3. **Authentication**: Uses the active PPTB connection

## 🤝 Contributing

Contributions are welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Submit a pull request

## 📄 License

MIT License - See LICENSE file for details

## 🙏 Acknowledgments

- Built for [Power Platform Toolbox](https://powerplatformtoolbox.com/)
- Inspired by the need for better Copilot Studio integration tools
- Thanks to the XrmToolBox community for inspiration

## 📧 Support

For issues, questions, or suggestions:
- Open an issue on GitHub
- Join the [PPTB Discord](https://discord.gg/yHXdyuqWva)

## 🔗 Related Resources

- [Power Platform Toolbox Documentation](https://docs.powerplatformtoolbox.com/)
- [Copilot Studio Documentation](https://learn.microsoft.com/en-us/microsoft-copilot-studio/)
- [Custom API Documentation](https://learn.microsoft.com/en-us/power-apps/developer/data-platform/custom-api)

---

**Made with ❤️ for the Power Platform community**